Start free

DEVELOPER DOCUMENTATION · V1

Build with
OpenCreative.

A practical reference for generating images, video, speech, music, avatars, and transcripts with one key.

Get an API key OpenAPI JSON

QUICKSTART

Your first output
in one request.

  1. 1Create a keyOpen Developer API & MCP in your dashboard. The secret is shown once.
  2. 2Keep it server-sideSet it as OPENCREATIVE_API_KEY. Never expose it in browser code.
  3. 3Make a requestAll endpoints share one Bearer token and workspace credit wallet.
cURL
curl https://www.opencreativehq.com/api/v1/images \
  -H "Authorization: Bearer $OPENCREATIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Editorial product photograph in warm morning light"}'

AUTHENTICATION

Bearer keys,
scoped to a workspace.

Send your key in the Authorization header on every request. Keys begin with oc_live_, are stored as one-way hashes, and can be revoked from the dashboard.

HTTP header
Authorization: Bearer oc_live_your_key

CREDITS & BILLING

One wallet.
Pay as you go.

API calls use the same credits as the OpenCreative studio. Add one-time Dodo Payments top-ups or use recurring plan credits. A generation reserves its estimated cost before provider work begins; failed jobs return that reservation.

Check your balance with GET /api/v1/credits. If it is too low, the API returns 402 before generation starts.

POST/api/v1/images

Create images

Generate a new image or run a specialist image operation. Completed assets include signed download URLs.

Parameters

promptstring · required

Creative direction, 3–8,000 characters.

aspectRatioenum

1:1, 16:9, 9:16, 4:3, or 3:4.

qualityenum

fast, standard, premium, or advanced.

countinteger

1–4 outputs.

operationstring

For example create-image, edit-image, or remove-background.

referencesURL[]

Up to five reference images.

idempotencyKeyUUID

Prevents duplicate generations on retries.

Request body
{
  "prompt": "Editorial product photo of a coral glass bottle",
  "aspectRatio": "1:1",
  "quality": "standard",
  "count": 1,
  "idempotencyKey": "0ab8f98c-5bfc-42a9-92a4-d7e519f89b41"
}
Response
{
  "generationId": "5a3e…",
  "status": "completed",
  "model": { "id": "…", "displayName": "…" },
  "assets": [{ "id": "…", "mime_type": "image/webp", "url": "https://…" }]
}
POST/api/v1/videos

Create video

Queue a video generation or transformation. Poll the returned generation ID until it completes.

Parameters

promptstring · required

Creative direction, 3–8,000 characters.

aspectRatioenum

16:9, 9:16, or 1:1.

durationinteger

3–10 seconds; supported values depend on the routed model.

resolutionenum

480p, 720p, or 1080p.

generateAudioboolean

Request native audio where the model supports it.

firstFrameURL

Starting frame for frame-to-video.

sourceVideoURL

Required by video editing operations.

referencesURL[]

Up to five visual references.

idempotencyKeyUUID

Recommended for every create call.

Request body
{
  "prompt": "Slow cinematic push-in, warm reflections, soft haze",
  "duration": 5,
  "aspectRatio": "16:9",
  "resolution": "720p",
  "quality": "standard",
  "idempotencyKey": "77fb8db3-2b1f-46de-928b-1189a588e3b2"
}
Response
{
  "generationId": "824f…",
  "status": "queued",
  "estimatedCredits": 24,
  "model": { "id": "…", "displayName": "…" }
}
POST/api/v1/speech

Generate speech

Synthesize speech and receive a signed audio URL in the response.

Parameters

textstring · required

Up to 10,000 characters.

voicestring

Voice identifier; defaults to alloy.

speednumber

0.7–1.3; defaults to 1.

qualityenum

fast, standard, or premium.

idempotencyKeyUUID

Prevents duplicate audio on retries.

Request body
{
  "text": "One idea. Every way it can move.",
  "voice": "alloy",
  "speed": 1,
  "quality": "standard"
}
Response
{
  "generationId": "a51c…",
  "status": "completed",
  "assetId": "841d…",
  "url": "https://…",
  "model": { "id": "…", "displayName": "…" }
}
POST/api/v1/music

Generate music

Create an original commercial-ready track from a creative brief.

Parameters

promptstring · required

Music brief, 10–3,000 characters.

moodstring

Creative mood; defaults to Cinematic.

instrumentalboolean

Defaults to true.

qualityenum

standard or premium.

idempotencyKeyUUID

Prevents duplicate tracks on retries.

Request body
{
  "prompt": "A restrained electronic pulse for a product reveal",
  "mood": "Cinematic",
  "instrumental": true,
  "quality": "standard"
}
Response
{
  "generationId": "92b7…",
  "status": "completed",
  "assetId": "64a0…",
  "url": "https://…",
  "credits": 12
}
POST/api/v1/avatars

Create avatar video

Queue a consented talking-presenter video. Poll the generation endpoint for the final asset.

Parameters

scriptstring · required

Spoken script, 3–5,000 characters.

referenceImageURL · required

Consented presenter image.

consenttrue · required

Confirms authorization to use the identity.

voiceAudioURL

Optional voice reference.

aspectRatioenum

16:9, 9:16, or 1:1.

durationinteger

5–30 seconds.

idempotencyKeyUUID

Recommended for every create call.

Request body
{
  "script": "Welcome to the next chapter of our product.",
  "referenceImage": "https://cdn.example.com/presenter.jpg",
  "consent": true,
  "aspectRatio": "9:16",
  "duration": 10
}
Response
{
  "generationId": "41de…",
  "status": "queued",
  "estimatedCredits": 36,
  "model": { "id": "…", "displayName": "…" }
}
POST/api/v1/transcriptions

Transcribe media

Transcribe base64-encoded audio or video into text and timestamped segments.

Parameters

base64string · required

Base64 media bytes, without a data-URL prefix.

formatenum · required

wav, mp3, flac, m4a, ogg, webm, aac, mp4, or mov.

languagestring

Optional ISO or BCP-47 source language code; omit it for auto detection.

durationSecondsnumber

Optional duration estimate, up to 3,600 seconds.

qualityenum

standard or premium.

idempotencyKeyUUID

Prevents duplicate transcription charges.

Request body
{
  "base64": "<base64 media bytes>",
  "format": "mp3",
  "language": "en",
  "quality": "standard"
}
Response
{
  "generationId": "73f9…",
  "status": "completed",
  "transcript": "Your transcript…",
  "language": "en",
  "segments": []
}
GET/api/v1/generations/{id}

Check generation

Fetch current status and signed output URLs for an asynchronous video or avatar render.

Parameters

idUUID · path

The generationId returned by a create call.

Response
{
  "generation": { "id": "824f…", "status": "completed", "capability": "video" },
  "assets": [{ "kind": "video", "mime_type": "video/mp4", "url": "https://…" }]
}
GET/api/v1/models?capability=video

List models

Read the curated live model catalog for image, video, speech, or transcription.

Parameters

capabilityquery enum

image, video, speech, or transcription; defaults to image.

Response
{
  "models": [{ "id": "…", "displayName": "…", "quality": "standard" }]
}
GET/api/v1/credits

Check credits

Read the current workspace credit balance used by both the API and studio.

Response
{ "balance": 486 }

ERRORS

Useful status codes.

400Invalid request or unsupported parameters.

401Missing, malformed, revoked, or expired credential.

402Workspace does not have enough credits.

403Creative API access is not enabled.

429Provider capacity or rate limit reached.

500Generation failed; reserved credits are returned.

SAFE RETRIES

Idempotency.

Include a fresh UUID in idempotencyKey for every logical create operation. Reusing that UUID returns the original generation instead of charging for a duplicate when your network retries.