Create a media process

Starts a generation process and charges team credits. V1 types: image-generation, video-generation, audio-generation, image-upscale, video-upscale, video-lipsync. The model must match the type (see GET /models). For seedance-2.5-edit, the first referenceVideos item is the required base video; editOperation defaults to edit, while extend, sequel, and prequel allow an omitted prompt. On seedance-2.5 and seedance-2.5-edit, every 480p run is a draft by default (send draft: false for a plain 480p render; draft: true also sets resolution 480), and draftVideoId (a draft's output assetId) on seedance-2.5 finishes that same shot at native 1080p within 7 days, edit drafts included; send it alone, since every other input comes from the draft. video-lipsync takes sourceVideoAssetId and audioAssetId from the team asset library; the server-measured audio duration determines its quote and charge. Sync-Max is train-once: omit trainingId on the first run, then reuse the trainingId returned on the process for faster later runs against the same trained source. Sync-Pro and Sync-v3 are single-shot and require no training. Always send an Idempotency-Key: retries with the same key and body return the original process instead of double-charging; the same key with a different body returns idempotency_conflict. input is validated per process type AND against the model's published capabilities (aspectRatios, resolutions, videoLengths from GET /models) — unsupported values are rejected with invalid_request, never silently coerced. Internal fields (batchId, filteringId, agent context) are ignored; pass sessionId instead to group the process and its outputs in a session (see /sessions), plus workspaceFolderId to file the outputs into a folder of that session's workspace as they finish. metadata (flat string/number/boolean/null values, max 16 keys) is echoed back on reads. webhookSecret is optional for legacy unsigned webhook delivery; when supplied with webhookUrl, notifications are HMAC-signed and may be attempted twice with a stable delivery id.

Authorization

bearerAuth processes:write

AuthorizationBearer <token>

In: header

Scope: processes:write

Header Parameters

Idempotency-Key?string

Stable caller-provided key for retry-safe process creation.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

type*string

Value in

"image-generation"
"video-generation"
"audio-generation"
"image-upscale"
"video-upscale"
"video-lipsync"

model*string

input*

Process-specific input, validated per process type. image-generation: prompt (string, required), aspectRatio (string), imageResolution (string), referenceImageUrls (string[]), referenceImages (({assetId} | {url})[]), promptUpsampling (boolean), disableAutoRetries (boolean), maskUrl (string), customSettings (object), outputName (string), promptItemCount (number), promptItemId (string), promptItemIndex (number), promptItemTitle (string). video-generation: prompt (string, required), genjutsuMode ("motion-transfer" | "object-swap"), editOperation ("edit" | "extend" | "sequel" | "prequel"), aspectRatio (string), resolution (number), draft (boolean), draftVideoId (string), taskType ("auto" | "reference" | "edit" | "extend"), seed (integer), videoLength (number), startingFrameImageUrl (string), endingFrameImageUrl (string), durationMode ("fixed" | "auto"), generateAudio (boolean), bitrateMode ("standard" | "high"), keyframes ({timeSeconds, imageUrl}[]), referenceImages (({assetId} | {url})[]), referenceVideos (({assetId} | {url})[]), referenceAudios (({assetId} | {url})[]), disableAutoRetries (boolean), customSettings (object), endingFrameImageRef (object), outputName (string), promptItemCount (number), promptItemId (string), promptItemIndex (number), promptItemTitle (string), startingFrameImageRef (object), stripAndReattachAudio (boolean). audio-generation: prompt (string, required), voiceId (string), referenceImages (({assetId} | {url})[]), referenceAudios (({assetId} | {url})[]), speed (number | string), language (string), volume (number), emotionString (string), pitch (number), multilingual (boolean), disableAutoRetries (boolean), outputName (string), promptItemCount (number), promptItemId (string), promptItemIndex (number), promptItemTitle (string). image-upscale: disableAutoRetries (boolean), upscaleFactor (number), imageAssetDocId (string), imageUrl (string), modelOptions (object), outputName (string), promptItemCount (number), promptItemId (string), promptItemIndex (number), promptItemTitle (string). video-upscale: prompt (string), disableAutoRetries (boolean), upscaleFactor (number), videoAssetId (string), videoUrl (string), modelOptions (object), outputName (string), promptItemCount (number), promptItemId (string), promptItemIndex (number), promptItemTitle (string). video-lipsync: sourceVideoAssetId (string, required), audioAssetId (string, required), trainingId (string), disableAutoRetries (boolean), endTimeSeconds (number), outputName (string), promptItemCount (number), promptItemId (string), promptItemIndex (number), promptItemTitle (string), startTimeSeconds (number). Model-specific limits (aspect ratios, resolutions, durations, reference counts) come from GET /models capabilities. seedance-2.5-edit requires referenceVideos[0] as its base video, forces automatic aspect ratio and duration, and accepts editOperation as edit (prompt required), extend, sequel, or prequel (prompt optional). seedance-2.5 and seedance-2.5-edit accept taskType (auto, reference, edit, extend; BytePlus omni_reference_task_type) and seed, and draft (480p runs are drafts by default; draft: false opts out); seedance-2.5 accepts draftVideoId (finish any draft at 1080p, edit drafts included; send it alone, other inputs come from the draft).

metadata?

Caller-owned metadata returned on process reads. Max 16 keys, 2 KB serialized.

webhookUrl?string

HTTPS URL notified when the process reaches completed or failed. Delivery is best-effort with up to two attempts; deduplicate by X-Yapper-Delivery-Id and fetch GET /processes/{processId} for the authoritative record. Include webhookSecret to authenticate deliveries.

Formaturi

webhookSecret?string

Optional caller-owned HMAC-SHA256 secret. When supplied, Yapper signs ${X-Yapper-Timestamp}.${rawBody} and sends the result as X-Yapper-Signature: v1=. Requires webhookUrl.

Length32 <= length <= 512

dryRun?boolean

Validate the request and return a 200 DryRunEstimate (cost + whether it can start) without creating a process or charging credits. A successful dry run means the identical real request would start.

testMode?boolean

Development environments only: run against a local test provider, spending no credits.

sessionId?string

Optional session (from GET or POST /sessions) that groups this work in the Yapper web app. Omit for no grouping.

workspaceFolderId?string

Optional folder id from GET /sessions/{sessionId}/workspace; the outputs are filed into it as they finish. Requires sessionId.

Response Body

`application/json`

curl -X POST "https://example.com/processes" \  -H "Content-Type: application/json" \  -d '{    "type": "image-generation",    "model": "gpt-image-2",    "input": {      "prompt": "A polished product photo of a stainless steel water bottle",      "aspectRatio": "1:1",      "imageResolution": "1080"    },    "metadata": {      "externalId": "job_123",      "customerUserId": "user_456"    }  }'

{  "dryRun": true,  "type": "string",  "model": "string",  "creditsEstimated": 0,  "canStart": true,  "blockedBy": "team_limit",  "fundingSource": "gimi_wallet",  "externalWallet": {    "provider": "gimi",    "requiredCents": 0,    "spendableCents": 0  },  "gimiWallet": {    "requiredCents": 0,    "spendableCents": 0  },  "credits": {    "available": 0,    "purchaseUrl": "string"  },  "estimatedCompletionSeconds": 0}

{  "id": "string",  "type": "string",  "status": "queued",  "model": "string",  "trainingId": "string",  "draft": {    "finishableUntil": "2019-08-24T14:15:22Z"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "completedAt": "2019-08-24T14:15:22Z",  "estimatedCompletionSeconds": 0,  "suggestedPollAfterSeconds": 0,  "creditsEstimated": 0,  "creditsUsed": 0,  "refunded": true,  "error": {    "code": "string",    "message": "string"  },  "input": {},  "outputs": [    {      "type": "image",      "assetId": "string",      "url": "http://example.com",      "thumbnailUrl": "http://example.com",      "preview": {        "url": "http://example.com",        "width": 0,        "height": 0,        "mimeType": "string"      },      "width": 0,      "height": 0,      "duration": 0,      "mimeType": "string"    }  ],  "metadata": {    "property1": "string",    "property2": "string"  },  "sessionId": "string",  "links": {    "self": "string"  }}

{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Authorization

Header Parameters

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

403application/json

409application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`