Spark 3D

Authentication

authorization string required

All APIs require authentication via Bearer Token.

Get API Key:

Visit API Key Management Page to get your API Key.

Usage:

Add to request header:

Authorization: Bearer YOUR_API_KEY

Parameters

model string required

Model ID to use for the request

Value: spark_3d

---

content array required

Input information for the model to generate 3D files. Must contain at least 2 items: text content and image content

Text Content Object

type string required

Content type

Value: text

text string required

Text content input to the model, including:

Parameters (optional): Control 3D file output specifications through --[parameters] format, see Model Text Commands (Optional) for details

Image Content Object

type string required

Content type

Value: image_url

image_url object required

Image URL object

url string required

Image information, can be image URL or Base64 encoded image

Image URL: Ensure the image URL is accessible

Base64 encoding: Follow this format data:image/<image_format>;base64,<base64_encoded>, note that <image_format> must be lowercase, e.g. data:image/png;base64,{base64_image}

Image requirements:
Total pixels: less than 4096×4096 px
Size: less than or equal to 10MB
Supported formats: jpg, jpeg, png, webp, bmp

---

Model Text Commands (Optional)

Control 3D file output specifications

Example:

"content": [
    {
        "type": "text",
        "text": "--subdivisionlevel medium --fileformat obj"
    }
]

subdivisionlevel string

Number of polygon faces in the 3D file

Default: medium

Abbreviation: sl

Options: high, medium, low

• high: 200000 faces (new)
• medium: 100000 faces
• low: 30000 faces (new)

---

fileformat string

Generated 3D file format

Default: glb

Abbreviation: ff

Options: glb, obj, usd, usdz

---

Polling

Since 3D model generation takes time, you need to poll the task status after creation

The initial response returns the task ID and initial status. The actual generation results must be obtained through polling the task status endpoint

Response Format

error object

Error information. Only present when status is failed

code string

Error code

error_message string

Detailed error message

---

output array

Generation results. Only present when status is completed

content array

List of generated 3D model content

type string

Resource type

Value: glb

url string

Generated 3D model file URL (processed and uploaded to CDN)

jobId string

Remote job ID

---

usage object

Usage statistics. Only present when status is completed

cost string

Total cost in USD

discount number

Discount amount

input_tokens integer

Number of input tokens (actual prompt_tokens)

output_tokens integer

Number of output tokens (actual completion_tokens)

total_tokens integer

Total number of tokens

created_at integer

Task creation timestamp

updated_at integer

Task update timestamp

---

metadata object

Metadata information

---

Error Codes

Error Code	Description
003020001	Missing text prompt
003020002	Missing image URL
003020003	Invalid subdivision level
003020004	Invalid file format
003020005	Invalid image URL format
003020095	Internal generation error
003020096	Result parsing error
003020097	HTTP error response
003020098	Status check error
003020099	Task creation error