QUADY3D API

3D Generation
API Documentation

Authenticate, discover supported models, approve a quote and follow the original task through generation, recovery and file download.

Build your first workflow SDK examples ↗

A generated lantern model with a loop handle, peaked roof and open frame — camping-lantern.glb GLB

BASE PATH/api/v1AUTHENTICATIONBearer API KeyOpenAPI 3.1 ↗

01 / CONNECT

A Key for your workflow.

Create a dedicated Key in Connected apps. Grant the scopes listed for the endpoints you need, then keep it in a trusted local or server environment.

HTTP request

GET /api/v1/account HTTP/1.1
Authorization: Bearer <YOUR_QUADY3D_API_KEY>
Accept: application/json

Keep credentials out of URLs, browser bundles and shared project files. Check GET /account for balance, download access and Key limits before a generation.

02 / CREATE & DELIVER

One task. Start to finish.

Use a quoted request and a stable action ID so a lost connection can be recovered without creating another generation.

01
Check the connection
Read the account balance, download access and Key limits. Discover an available model and its parameter schema for your chosen input.
02
Get a quote
Quote the exact operation, model, inputs and parameters. Quotes do not reserve generation credits. Check the quoted cost against the user's approved budget.
03
Save, then submit
Before POST /jobs, save the exact request body and a unique Idempotency-Key. Submit with quote_id and max_credits. Keep the returned job ID.
04
Resume the same task
Poll GET /jobs/{id} until succeeded or failed. A timeout or submission_unknown needs recovery of the original request, without creating a replacement task.
05
Save the actual file
Use an asset's download_path from the completed job. Stream to a temporary file, validate the actual file and publish to the approved destination without overwriting an existing file.

Starting from an image?

Upload one selected PNG, JPEG or WebP as a raw body, up to 8 MiB. Use its returned upload ID when requesting a quote. Discover each model’s input limits and settings with GET /models.

Model API reference ↗TypeScript guide ↗Python guide ↗Complete executable examples ↗

03 / REFERENCE

The endpoints you need.

All paths below are relative to /api/v1. Expand an endpoint for its required scopes, input fields and response codes.

GET/modelsList public model capabilities

List public model capabilities

Required scope: models:read

Parameters

Field	Type	Details
`operation`Optional	`text-to-3d \| image-to-3d`	query.

Responses

200Available models, input limits and parameter names. ModelList
400A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
401A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
402A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
403A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
404A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
409A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
410A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
413A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
415A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
429A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
503A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse

GET/accountRead balance, rights and Key limits

Read balance, rights and Key limits

Required scope: account:read

Responses

200Public credit balance and existing account rights. Account
400A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
401A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
402A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
403A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
404A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
409A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
410A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
413A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
415A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
429A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
503A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse

POST/uploadsStage a selected input without a generation charge

Send a single raw PNG, JPG or WebP body, up to 8 MiB. No multipart wrapper, base64 or remote URL. When advanced operations are enabled, embedded GLB 2.0 models up to 50 MiB are also accepted as model/gltf-binary. Model dependencies must be embedded, with no URI references. Use source_upload_id for model processing. The immutable owned upload can be reused until expires_at; active task references protect its bytes after expiry.

Required scope: uploads:write

Content-Type: image/png image/jpeg image/webp · maximum 8,388,608 bytes

Responses

201An owned upload ID and its expiry, not an object key. UploadedImage
400A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
401A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
402A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
403A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
404A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
409A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
410A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
413A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
415A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
429A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
503A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse

POST/quotesQuote normalized model inputs

Quote normalized model inputs

Required scope: jobs:write

Content-Type: application/json

text-to-3d

Field	Type	Details
`operation`Required	`"text-to-3d"`	—
`model`Required	`tripo-h3-1 \| rodin-2-5-fast \| hunyuan-3-1-rapid \| hunyuan-3 \| hunyuan-3-1-pro \| rodin-2-5 \| tripo-p2 \| meshy-7-1 \| gpt-6-astra`	—
`inputs`Required	`object`	—
`inputs.prompt`Required	`string`	Minimum length: 1. Maximum length: 1000.
`parameters`Optional	`object`	Model-specific parameter names are listed by GET /models. Values follow that model's supported bounds.

image-to-3d

Field	Type	Details
`operation`Required	`"image-to-3d"`	—
`model`Required	`tripo-h3-1 \| hunyuan-2-mini \| rodin-2-5-fast \| trellis-2 \| pixal3d \| hunyuan-3-1-rapid \| hunyuan-3 \| seed3d-2 \| hunyuan-3-1-pro \| rodin-2-5 \| tripo-p2 \| meshy-7-1 \| hi3d-3 \| gpt-6-astra`	—
`inputs`Required	`object`	—
`inputs.upload_ids`Required	`string[]`	Minimum items: 1. Maximum items: 1.
`parameters`Optional	`object`	Model-specific parameter names are listed by GET /models. Values follow that model's supported bounds.

Responses

201A five-minute quote; no credits reserved. Quote
400A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
401A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
402A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
403A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
404A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
409A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
410A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
413A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
415A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
429A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
503A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse

POST/jobsCreate or recover an idempotent generation

Persist a unique action ID before sending. Reuse the exact body and Idempotency-Key on retry. An accepted replay survives quote/input expiry and returns the original job. Account balance, concurrency and Key budgets are checked together before a provider submission.

Required scope: jobs:write

Parameters

Field	Type	Details
`Idempotency-Key`Required	`string`	header. Minimum length: 1. Maximum length: 128. Pattern: ^[!-~]+$

Content-Type: application/json

text-to-3d

Field	Type	Details
`operation`Required	`"text-to-3d"`	—
`model`Required	`tripo-h3-1 \| rodin-2-5-fast \| hunyuan-3-1-rapid \| hunyuan-3 \| hunyuan-3-1-pro \| rodin-2-5 \| tripo-p2 \| meshy-7-1 \| gpt-6-astra`	—
`inputs`Required	`object`	—
`inputs.prompt`Required	`string`	Minimum length: 1. Maximum length: 1000.
`parameters`Optional	`object`	Model-specific parameter names are listed by GET /models. Values follow that model's supported bounds.
`quote_id`Required	`string`	Pattern: ^quo_[a-f0-9]{32}$
`max_credits`Required	`number`	Greater than 0. Maximum: 1000000.

image-to-3d

Field	Type	Details
`operation`Required	`"image-to-3d"`	—
`model`Required	`tripo-h3-1 \| hunyuan-2-mini \| rodin-2-5-fast \| trellis-2 \| pixal3d \| hunyuan-3-1-rapid \| hunyuan-3 \| seed3d-2 \| hunyuan-3-1-pro \| rodin-2-5 \| tripo-p2 \| meshy-7-1 \| hi3d-3 \| gpt-6-astra`	—
`inputs`Required	`object`	—
`inputs.upload_ids`Required	`string[]`	Minimum items: 1. Maximum items: 1.
`parameters`Optional	`object`	Model-specific parameter names are listed by GET /models. Values follow that model's supported bounds.
`quote_id`Required	`string`	Pattern: ^quo_[a-f0-9]{32}$
`max_credits`Required	`number`	Greater than 0. Maximum: 1000000.

Responses

202A durable job. Immediate definitive rejection is represented as a failed job with its actual refund. Job
400A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
401A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
402A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
403A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
404A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
409A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
410A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
413A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
415A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
429A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
503A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse

GET/jobsList owned API tasks

List owned API tasks

Required scope: jobs:read

Parameters

Field	Type	Details
`limit`Optional	`integer`	query. Minimum: 1. Maximum: 100. Default: 20.
`cursor`Optional	`string`	query. Pattern: ^[0-9]{1,12}:int_[a-f0-9]{64}$
`status`Optional	`submitting \| submission_unknown \| queued \| processing \| succeeded \| failed`	query.

Responses

200Newest tasks first with a stable cursor. JobList
400A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
401A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
402A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
403A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
404A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
409A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
410A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
413A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
415A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
429A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
503A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse

GET/jobs/{id}Query and reconcile the same owned task

A transient provider error is not proof of failure. submission_unknown remains recoverable and must not be replaced by a new creation.

Required scope: jobs:read

Parameters

Field	Type	Details
`id`Required	`string`	path. Pattern: ^int_[a-f0-9]{64}$

Responses

200The durable public task state, credit amounts and actual assets. Job
400A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
401A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
402A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
403A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
404A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
409A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
410A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
413A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
415A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
429A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
503A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse

GET/assets/{id}Download an owned asset

Ownership, retention and download rights are checked before file delivery. Save into an authorized temporary file, validate it, then publish without overwriting an existing file.

Required scope: assets:read

Parameters

Field	Type	Details
`id`Required	`string`	path. Pattern: ^[a-zA-Z0-9_-]+$

Responses

200Streamed binary file with its actual Content-Type and attachment filename.
206Partial file for a valid byte range.
304Unmodified owned file after current access checks.
400A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
401A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
402A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
403A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
404A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
409A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
410A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
412A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
413A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
415A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
416A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
429A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
503A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse

GET/openapiRead the API contract

Read the API contract

Public endpoint · no Key required

Responses

200Machine-readable OpenAPI document, available when API access is enabled.
400A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
429A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse
503A stable error. Retry writes only with the original Idempotency-Key and body. ErrorResponse

04 / RESPONSE FIELDS

Read the actual result.

Use the returned account, quote, job and asset fields. Available formats and generation settings depend on the chosen model.

Account

Field	Type	Details
`account_id`Required	`string`	Stable account comparison value across Keys from the same API. Not a credential; bind local recovery to both API address and account_id. Pattern: ^acc_[a-f0-9]{64}$
`balance_credits`Required	`number`	Public credits, already converted from ledger units. Minimum: 0.
`plan`Required	`string`	—
`download_access`Required	`boolean`	—
`key_limits`Required	`object`	—
`key_limits.max_job_credits`Required	`integer`	Minimum: 0.
`key_limits.daily_credits`Required	`integer`	Minimum: 0.
`request_id`Required	`string`	—

ModelList

Field	Type	Details
`data`Required	`object[]`	—
`generation_operations`Required	`text-to-3d \| image-to-3d[]`	—
`request_id`Required	`string`	—

Model

Field	Type	Details
`id`Required	`string`	—
`name`Required	`string`	—
`maker`Required	`string`	—
`operation`Required	`text-to-3d \| image-to-3d`	—
`available`Required	`boolean`	—
`unavailable_reason`Required	`string \| null`	—
`estimated_credits`Required	`number \| null`	Minimum: 0.
`parameter_names`Required	`string[]`	—
`parameter_schema`Required	`object`	Version 1 JSON Schema subset: typed properties, defaults, bounds, enums, and conditional allOf limits. x- annotations describe controls; admission remains server-validated.
`input`Required	`object`	—
`capabilities`Required	`object`	—

UploadedImage

Field	Type	Details
`id`Required	`string`	Pattern: ^upl_[a-f0-9]{32}$
`content_type`Required	`image/png \| image/jpeg \| image/webp`	—
`byte_size`Required	`integer`	Minimum: 1. Maximum: 8388608.
`sha256`Required	`string`	Pattern: ^[a-f0-9]{64}$
`expires_at`Required	`integer`	Minimum: 0.
`request_id`Required	`string`	—

Quote

Field	Type	Details
`id`Required	`string`	Pattern: ^quo_[a-f0-9]{32}$
`operation`Required	`text-to-3d \| image-to-3d`	—
`model`Required	`string`	—
`credits`Required	`number`	Public credits, already converted from ledger units. Minimum: 0.
`price_version`Required	`string`	—
`expires_at`Required	`integer`	Minimum: 0.
`download_access`Required	`boolean`	—
`request_id`Required	`string`	—

Job

Field	Type	Details
`id`Required	`string`	Pattern: ^int_[a-f0-9]{64}$
`operation`Required	`text-to-3d \| image-to-3d`	—
`model`Required	`string`	—
`status`Required	`submitting \| submission_unknown \| queued \| processing \| succeeded \| failed`	—
`stage`Optional	`string`	—
`credits`Required	`object`	—
`credits.reserved`Required	`number`	Public credits, already converted from ledger units. Minimum: 0.
`credits.charged`Required	`number`	Public credits, already converted from ledger units. Minimum: 0.
`credits.refunded`Required	`number`	Public credits, already converted from ledger units. Minimum: 0.
`assets`Required	`object[]`	—
`created_at`Required	`integer`	Minimum: 0.
`expires_at`Optional	`integer \| null`	Minimum: 0.
`files_expired`Optional	`boolean`	—
`error`Optional	`object`	—
`error.code`Optional	`string`	—
`error.message`Optional	`string`	—
`request_id`Required	`string`	—

Asset

Field	Type	Details
`id`Required	`string`	—
`format`Required	`string`	—
`role`Required	`string \| null`	—
`content_type`Required	`string`	—
`byte_size`Required	`integer \| null`	Minimum: 0.
`download_path`Required	`string`	Pattern: ^/api/v1/assets/[a-zA-Z0-9_-]+$

JobList

Field	Type	Details
`data`Required	`object[]`	—
`next_cursor`Required	`string \| null`	—
`request_id`Required	`string`	—

ErrorResponse

Field	Type	Details
`error`Required	`object`	—
`error.code`Required	`string`	—
`error.message`Required	`string`	—
`error.request_id`Required	`string`	—
`error.retryable`Required	`boolean`	—

05 / KEEP YOUR PROGRESS

Resume where you left off.

Save the API address, account, action ID, exact body and job ID. When a response is lost, query the known job or replay the original request with its original Idempotency-Key.

submitting

Submission is being processed. Keep the job and wait.

submission_unknown

Submission is unresolved. Query the original job; do not create a replacement.

queued

The job is accepted and waiting. Continue checking the same job.

processing

Generation is running. Continue checking the same job.

succeeded

Read the actual assets, formats and download paths before saving files.

failed

Read the job error and actual charged/refunded amounts. A new generation is a separate user action.

A retry keeps the original task.

An accepted replay returns the same job even after the quote or input expires. A timeout, uncertain submission or failed download does not authorize another generation. If a file download stops, recover that asset and save to a new, approved path.

06 / HANDLE ERRORS

A clear next step.

API errors return error.code, error.message, error.request_id and error.retryable. Keep the request ID for support. Honor Retry-After when present.

400: Correct the request fields using the model and endpoint schemas.
401 / 403: Check the Key, account, required scopes and download access. Keep credentials out of URLs and client-side code.
402: Check the account balance and credit limits. Obtain approval before increasing a budget.
404 / 410: Check the owned resource ID, connection and expiry. An unavailable download does not authorize another generation.
409: Read error.code. An idempotency conflict requires the original saved request. Only refresh an expired quote for a request confirmed unaccepted; do not replace an unresolved submission.
413 / 415: Use a supported raw image and stay within the upload byte limit.
429 / 503: Honor Retry-After when present. Recover writes with the same Idempotency-Key and body; avoid rapid retry loops.
412 / 416: Review download preconditions or the requested byte range before trying the same asset again.

Agent documentation index ↗Read as Markdown ↗

3D GenerationAPI Documentation

A Key for your workflow.

One task. Start to finish.

Check the connection

Get a quote

Save, then submit

Resume the same task

Save the actual file

The endpoints you need.

Parameters

Responses

Responses

Responses

text-to-3d

image-to-3d

Responses

Parameters

text-to-3d

image-to-3d

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Responses

Read the actual result.

Resume where you left off.

A clear next step.

3D Generation
API Documentation