Sketchfab 3D AI Model Search Actor

An Apify actor that searches Sketchfab for 3D models using a combined strategy of query, tags, and categories. It includes an optional AI layer (LangGraph + Google Gemini) to convert natural language descriptions into optimized search parameters.

Overview

This actor performs searches on Sketchfab's API. It has two modes: a manual mode where you specify search parameters directly, and an AI mode where you provide a plain-text description. The AI processes your description and extracts relevant search terms, tags, and categories. All searches support pagination to browse through large result sets.

Key Features

• Dual Search Modes: Use precise manual filters or let the AI convert natural language into search parameters.
• Combined Search Strategy: Searches use a combination of the query (q), tags, and categories simultaneously for better results.
• AI-Powered NLP: Leverages Google Gemini to break down long user descriptions into concise, SEO-optimized queries and relevant tags.
• Full Pagination: Implements cursor-based pagination to navigate through all available results.
• Structured Output: Returns validated, type-safe data using Pydantic models, including pagination metadata.
• Smart Defaults: Automatically sets downloadable=true and can infer categories from the search context.

How to Use

Configure the actor run via input JSON. You must provide either manual parameters or a natural language query for the AI.

Mode 1: AI-Powered Natural Language Search

Set useAI to true and provide a descriptive naturalQuery. You must also supply a googleApiKey.

{
  "useAI": true,
  "naturalQuery": "a futuristic cyberpunk sports car with neon lights, low-poly for a game",
  "googleApiKey": "your-gemini-api-key",
  "count": 24
}

The AI will transform this into structured search parameters like q: "cyberpunk sports car", tags: ["cyberpunk", "low-poly"], and categories: ["cars-vehicles"].

Mode 2: Manual Search

Set useAI to false (or omit it) and specify parameters directly.

{
  "useAI": false,
  "q": "robot warrior",
  "tags": ["sci-fi", "mech"],
  "categories": ["science-technology"],
  "animated": true,
  "downloadable": true,
  "count": 24
}

Pagination

To get more results, use the cursor value returned in the output.

Input for next page:

{
  "useAI": false,
  "q": "cars",
  "cursor": "cD0yNA==",
  "count": 24
}

Input/Output

Input Schema (JSON):
* useAI (boolean): Required. Switches between AI and manual mode.
* naturalQuery (string): Required if useAI=true. The text description for the AI to process.
* googleApiKey (string): Required if useAI=true. Your Google AI Studio API key for Gemini.
* q (string): The main search query (used in manual mode or overrides AI query).
* tags (array of strings): Filter by tags.
* categories (array of strings): Filter by Sketchfab categories.
* cursor (string): Pagination cursor from a previous result.
* count (integer, default 24): Number of results per page.
* downloadable (boolean, default true): Filter for downloadable models.
* animated (boolean): Filter for animated models.

Output:
The actor stores results in the Apify dataset. Each item is a structured 3D model object from Sketchfab. The dataset also contains a _metadata object with pagination information:

{
  "_metadata": {
    "totalCount": 1250,
    "nextCursor": "cD00OA==",
    "previousCursor": null
  }
}