Generating media

A generation is a job. You start it, it costs credits, and you poll it until media comes out. Nothing about it blocks: a photo takes around 30 seconds and a video several minutes.

Tools, not models

You address a tool (ugc-video, text-to-photo, lipsync), and the platform picks the right model and pipeline. Pass model only when you specifically want to override it.

curl https://api.creatorline.io/v1/models \
  -H "Authorization: Bearer $CREATORLINE_API_KEY"

Read the catalog, don’t hardcode it. GET /v1/models returns every tool, every model, and the exact inputs and parameters each accepts. When we add a model, your code can use it without a change on your side. Narrow with ?tool=ugc-video or ?model=<id>.

Each model entry describes itself completely enough to build a call from it alone:

Field	What it settles
`prompt.required`	Whether the call needs a `prompt` at all.
`inputs[]`	Every slot, with `label`, `hint`, `modality`, `required`, and `max` (absent = no limit).
`params[].values`	The fixed set a parameter accepts.
`params[].options`	What those values mean, when they are opaque (caption styles, scene modes).
`params[].min` / `max` / `step`	The bounds of a numeric dial that has no fixed set — `duration` is one.
`params[].control`	`voice` means the value is a voice id from `GET /v1/voices`.
`max_count`	The highest `count` this model accepts.
`max_duration_sec`	The longest single take it produces.

Video

ugc-video · short-clip · scene-video · motion-control · hook-captions

Photo

text-to-photo · photo-edit

Audio

text-to-speech · lipsync · change-voice · add-audio · dialogue

Generating as a creator

Pass account_id and the run inherits that creator’s look, voice and persona, and the output lands on their wall in the studio. Without it, the run is workspace-scoped and generic.

curl https://api.creatorline.io/v1/accounts \
  -H "Authorization: Bearer $CREATORLINE_API_KEY"

Concretely, account_id does two things you can override:

boolean

default:"true"

The creator’s avatar is added to the model’s character slot, which is what keeps their face consistent across runs. Set it to false when the output must not contain them — a product shot posted on their account, a scene they are not in.

string

Any voice parameter (voice_id, voice_a, voice_b) defaults to that creator’s own cloned voice, the same one the studio pins. Pass one explicitly to use a different voice.

Voices

Three tools speak: text-to-speech, dialogue and change-voice. Their voice parameters carry control: "voice" in the catalog and take an id from:

curl "https://api.creatorline.io/v1/voices?search=warm" \
  -H "Authorization: Bearer $CREATORLINE_API_KEY"

?scope=library searches the public shared library instead of your own and cloned voices, and takes ?gender= and ?language=. A creator’s cloned voice is on their account as voice_id.

Inputs and parameters

object

Slot key → asset id(s) or public https URL(s). A URL is adopted as an asset automatically, so there is no upload step when your media is already on the internet. Which slots a model takes — and which are required — is in its catalog entry.

object

Model parameters like aspect_ratio, duration, resolution. Validated against the model’s schema.

An unknown parameter is a 400, never a silent drop. A typo’d parameter quietly ignored on a paid call is the worst possible outcome, so we refuse the call instead.

{
  "tool": "ugc-video",
  "prompt": "unboxing a skincare set, chatty and warm",
  "account_id": "e307923d-…",
  "inputs": { "characters": ["https://example.com/face.png"] },
  "params": { "aspect_ratio": "9:16", "duration": "5" }
}

Working from a video link

A tool whose catalog entry carries accepts_source_url (today short-clip) takes a video link instead of an uploaded file. Pass source_url or the source asset in inputs, never both — and one of them is required, so a run cannot be charged for a source that was never there.

{ "tool": "short-clip", "source_url": "https://www.youtube.com/watch?v=…" }

Modes that need a second input

Some parameters unlock an input rather than a value. Seedance’s storyboard scene mode is the one to know: "reference" (the default) shoots from your character and reference images, while "storyboard" analyses a source video into a storyboard sheet, casts your creator into it, and reshoots it — so it needs inputs.source_video too.

{
  "tool": "ugc-video",
  "prompt": "recreate this hook, same energy",
  "account_id": "e307923d-…",
  "inputs": {
    "characters": ["https://example.com/face.png"],
    "source_video": "https://example.com/trend.mp4"
  },
  "params": { "storyboard": "storyboard", "duration": 8 }
}

Uploading your own media

Bytes never pass through the API. Three steps, and the asset id is usable the moment the PUT succeeds:

Ask for a presigned upload

POST /v1/uploads with content_type and size_bytes. You get upload_url, headers and the asset_id it will become.

PUT the bytes

Straight to storage, with the headers you were given.

Complete it

POST /v1/uploads/{id}/complete. This starts thumbnailing and transcoding, and hands you the finished asset. A video or audio upload is also probed here, so the asset comes back with its real duration_sec and ratio — which is what lets a source-billed run be priced correctly. The probe reads a few KB over range requests, not the whole file.

Limits: images 25 MB, video 100 MB, audio 50 MB. The CLI does all three for you — --image ./face.png just works.

Cost

curl https://api.creatorline.io/v1/generations/cost \
  -H "Authorization: Bearer $CREATORLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tool": "ugc-video", "params": { "duration": "10" } }'

{ "object": "cost_estimate", "model": "bytedance-seedance-2-0-reference-to-video-fast",
  "credits": 48, "credit_balance": 4433, "sufficient": true }

Free to call, available to read keys, and priced by the same function that performs the debit — so an estimate cannot disagree with the charge. Credits are taken at kick-off; a run that terminally fails, including a moderation rejection, is refunded automatically.

Send the media when you price a source-billed run. lipsync, motion-control, scene-video, change-voice and short-clip charge per second of the source, not of the output. Pass the same inputs / source_url the real run will use and the estimate returns the duration_sec it billed; without them it can only quote a default length. An asset id, an https URL and a source_url link all resolve to the real length, so the quote matches the charge either way.

Polling

queued → processing → succeeded
                    ↘ failed

Poll GET /v1/generations/{id} every few seconds. On succeeded, output[] holds the assets:

{
  "object": "generation",
  "id": "3f6c1a2b-…",
  "status": "succeeded",
  "output": [
    { "object": "asset", "id": "9b2f7c10-…", "file_type": "video",
      "ratio": "9:16", "duration_sec": 5, "url": "https://…/clip.mp4" }
  ]
}

Media URLs are time-limited. Download the bytes; do not persist the link.

On failed, error carries the reason — a moderation rejection reads differently from a provider failure — and your credits are already back.

Publish it

Turn finished media into a post on your creator’s social accounts.

Full reference

Every field, with a live playground.

Get started

Guides

API reference

Tools, not models

Video

Photo

Audio

Generating as a creator

Voices

Inputs and parameters

Working from a video link

Modes that need a second input

Uploading your own media

Cost

Polling

Next

Publish it

Full reference

​Tools, not models

Video

Photo

Audio

​Generating as a creator

​Voices

​Inputs and parameters

​Working from a video link

​Modes that need a second input

​Uploading your own media

​Cost

​Polling

​Next

Publish it

Full reference

Tools, not models

Generating as a creator

Voices

Inputs and parameters

Working from a video link

Modes that need a second input

Uploading your own media

Cost

Polling

Next