curl --request POST \
  --url https://api.creatorline.io/v1/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tool": "text-to-photo",
  "prompt": "matcha latte flatlay on a linen tablecloth, morning light",
  "params": {
    "aspect_ratio": "4:5",
    "resolution": "2K"
  }
}
'

{
  "object": "generation",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "queued",
  "output": [
    {
      "object": "asset",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "<string>",
      "file_type": "image",
      "title": "<string>",
      "ratio": "<string>",
      "duration_sec": 123,
      "url": "<string>",
      "thumbnail_url": "<string>",
      "mime_type": "<string>",
      "size_bytes": 123,
      "source": "<string>",
      "status": "<string>",
      "tool": "<string>",
      "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "tool": "<string>",
  "stage": "<string>",
  "model": "<string>",
  "prompt": "<string>",
  "params": {},
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": "<string>",
  "created_at": 123,
  "updated_at": 123
}

{
  "object": "generation",
  "id": "3f6c1a2b-8d4e-4c11-9a77-2b8f0e5d1c93",
  "status": "queued",
  "tool": "ugc-video",
  "stage": "video-ref",
  "model": "bytedance-seedance-2-0-reference-to-video-fast",
  "count": 1,
  "ratio": "9:16",
  "file_type": "video",
  "credits_charged": 30,
  "credit_balance": 4403,
  "output": []
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Invalid value for \"aspect_ratio\": \"99:99\". Allowed: 1:1, 9:16, 16:9.",
    "param": "params.aspect_ratio"
  },
  "request_id": "req_8fQ2mRxK1pLd"
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Missing or invalid API key."
  },
  "request_id": "req_8fQ2mRxK1pLd"
}

{
  "error": {
    "type": "insufficient_credits_error",
    "code": "insufficient_credits",
    "message": "This request costs 30 credits and the workspace has 12."
  },
  "request_id": "req_8fQ2mRxK1pLd",
  "required_credits": 30,
  "credit_balance": 12
}

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key is read-only. Create a key with the `write` scope to run generations."
  },
  "request_id": "req_8fQ2mRxK1pLd"
}

{
  "error": {
    "type": "not_found_error",
    "code": "resource_missing",
    "message": "No such generation."
  },
  "request_id": "req_8fQ2mRxK1pLd"
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry."
  },
  "request_id": "req_8fQ2mRxK1pLd"
}

Generations

Start a generation

Start an image or video run. This is the API’s one paid operation and it is asynchronous by design: a video takes minutes, so the call returns a job handle immediately and you poll GET /v1/generations/{id}.

inputs values are either an asset id or a public https URL (adopted as an asset automatically). params are validated against the model’s own schema — an unknown key is a 400, never a silent drop, because a silently ignored parameter on a paid call is the worst possible outcome.

Send Idempotency-Key and a retry returns the ORIGINAL generation instead of paying for a second run.

POST

generations

curl --request POST \
  --url https://api.creatorline.io/v1/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tool": "text-to-photo",
  "prompt": "matcha latte flatlay on a linen tablecloth, morning light",
  "params": {
    "aspect_ratio": "4:5",
    "resolution": "2K"
  }
}
'

{
  "object": "generation",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "queued",
  "output": [
    {
      "object": "asset",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "<string>",
      "file_type": "image",
      "title": "<string>",
      "ratio": "<string>",
      "duration_sec": 123,
      "url": "<string>",
      "thumbnail_url": "<string>",
      "mime_type": "<string>",
      "size_bytes": 123,
      "source": "<string>",
      "status": "<string>",
      "tool": "<string>",
      "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "tool": "<string>",
  "stage": "<string>",
  "model": "<string>",
  "prompt": "<string>",
  "params": {},
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "error": "<string>",
  "created_at": 123,
  "updated_at": 123
}

{
  "object": "generation",
  "id": "3f6c1a2b-8d4e-4c11-9a77-2b8f0e5d1c93",
  "status": "queued",
  "tool": "ugc-video",
  "stage": "video-ref",
  "model": "bytedance-seedance-2-0-reference-to-video-fast",
  "count": 1,
  "ratio": "9:16",
  "file_type": "video",
  "credits_charged": 30,
  "credit_balance": 4403,
  "output": []
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Invalid value for \"aspect_ratio\": \"99:99\". Allowed: 1:1, 9:16, 16:9.",
    "param": "params.aspect_ratio"
  },
  "request_id": "req_8fQ2mRxK1pLd"
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Missing or invalid API key."
  },
  "request_id": "req_8fQ2mRxK1pLd"
}

{
  "error": {
    "type": "insufficient_credits_error",
    "code": "insufficient_credits",
    "message": "This request costs 30 credits and the workspace has 12."
  },
  "request_id": "req_8fQ2mRxK1pLd",
  "required_credits": 30,
  "credit_balance": 12
}

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key is read-only. Create a key with the `write` scope to run generations."
  },
  "request_id": "req_8fQ2mRxK1pLd"
}

{
  "error": {
    "type": "not_found_error",
    "code": "resource_missing",
    "message": "No such generation."
  },
  "request_id": "req_8fQ2mRxK1pLd"
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry."
  },
  "request_id": "req_8fQ2mRxK1pLd"
}

Authorizations

Authorization

string

header

required

Your organization's API key, from Settings → MCP. Authorization: Bearer crl_sk_live_…

Headers

Idempotency-Key

string

A UUID you generate. A replay returns the original generation with idempotent-replay: true. Keys are namespaced per API key and kept for 24 hours.

Maximum string length: 255

Body

application/json

account_id

string<uuid>

required

Required. Generate as this creator — inherits their look, voice and persona, and the run lands in their API project.

tool

enum<string>

The tool to run. Preferred over stage.

Available options:

ugc-video,

reshoot,

short-clip,

scene-video,

motion-control,

hook-captions,

merge-clips,

photo-edit,

text-to-photo,

add-audio,

lipsync,

change-voice,

text-to-speech,

dialogue

stage

string

Lower-level escape hatch when you want to address a stage directly.

model

enum<string>

Override the tool's default model. Must belong to the tool's stage.

Available options:

nano-banana-pro,

nano-banana-2-text-to-image,

gpt-image-v2-text-to-image,

nano-banana-pro-edit,

nano-banana-2-edit,

bytedance-seedream-v4-5-edit,

gpt-image-v2-edit,

bytedance-seedance-2-5-image-to-video,

bytedance-seedance-2-0-image-to-video,

bytedance-seedance-2-0-image-to-video-fast,

xai-grok-imagine-video-1-5-preview-image-to-video,

minimax-h3-max-image-to-video,

minimax-h3-max-turbo-image-to-video,

kling-v3-4k-image-to-video,

kling-v3-pro-image-to-video,

kling-v3-standard-image-to-video,

kling-o3-standard-image-to-video,

google-gemini-omni-flash-image-to-video,

veo-3-1-lite-text-to-video,

veo-3-1-lite-first-last-frame-to-video,

veo3-1-text-to-video,

veo3-1-first-last-frame-to-video,

veo3-1-first-last-frame-to-video-fast,

veo3-1-reference-to-video,

flux-3-text-to-video,

flux-3-image-to-video-timestamped,

bytedance-seedance-2-0-reference-to-video,

bytedance-seedance-2-0-mini-reference-to-video,

bytedance-seedance-2-0-reference-to-video-fast,

bytedance-seedance-2-5-reference-to-video,

xai-grok-imagine-reference-to-video,

google-gemini-omni-flash-reference-to-video,

kling-v3-standard-motion-control,

hook-write,

caption-burn,

short-clip,

bytedance-seedance-2-0-text-to-video,

minimax-h3-max-text-to-video,

minimax-h3-max-turbo-text-to-video,

sync-3-lipsync,

sync-lipsync-v2-pro,

ffmpeg-api-merge-audio-video,

elevenlabs-zrm-text-to-speech,

elevenlabs-zrm-text-to-dialogue,

change-voice,

merge-clips,

scene-seedance-2-5,

reshoot-seedance-2-0,

reshoot-seedance-2-5,

scene-seedance-2-0,

scene-seedance-2-0-mini,

scene-kling-o3-pro-reference,

scene-seedance-2-0-fast,

scene-kling-o3-standard-reference,

scene-kling-o3-pro-edit,

scene-kling-o3-standard-edit

prompt

string

What to create. Required by most models.

avatar_id

string

The avatar the run renders with (from GET /v1/avatars): its face goes into the model's character slot and its voice is the default for any voice parameter. Must belong to your workspace (404 otherwise). Omit to use the account's default avatar.

inputs

object

Slot key → asset id(s) or public https URL(s), per the model's inputs. A URL is adopted as an asset automatically.

Show child attributes

params

object

Model parameters. Validated against the model's schema — an unknown key is a 400.

Show child attributes

count

integer

Alternatives to produce, up to the model's max_count. Image models only; video is always one take.

Required range: 1 <= x <= 4

source_url

string<uri>

For a tool with accepts_source_url (today short-clip): the video LINK to work from, instead of uploading it. Pass this OR the source asset in inputs, never both. The run is priced off the link's real length.

include_account_avatar

boolean

default:true

The creator's avatar is added to the model's character slot so they stay recognisable across runs. Set false when the output must NOT contain the creator (a product shot on their account, a scene without them).

Response

An idempotent replay: the original generation, unchanged and not re-charged.

object

enum<string>

required

Available options:

generation

string<uuid>

required

status

enum<string>

required

Available options:

queued,

processing,

succeeded,

failed

output

object[]

required

Show child attributes

tool

string

stage

string

model

string

prompt

string

params

object

account_id

string<uuid>

error

string

Present on failed. The credits were refunded.

created_at

number

updated_at

number

Get started

Guides

API reference

Start a generation

Authorizations

Headers

Body

Response