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. 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. 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:writeIn: header
Scope: processes:write
Header Parameters
Stable caller-provided key for retry-safe process creation.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
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", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "completedAt": "2019-08-24T14:15:22Z", "estimatedCompletionSeconds": 0, "creditsEstimated": 0, "creditsUsed": 0, "error": { "code": "string", "message": "string" }, "input": {}, "outputs": [ { "type": "image", "assetId": "string", "url": "http://example.com", "thumbnailUrl": "http://example.com", "width": 0, "height": 0, "duration": 0, "mimeType": "string" } ], "metadata": { "property1": "string", "property2": "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" }}Create a direct upload POST
For local image, video, or audio files with no URL (use POST /assets/import for remote media). Returns a short-lived signed PUT URL: upload the bytes to uploadUrl sending every header from the response headers map (Content-Type plus the x-goog-content-length-range size cap — the storage provider rejects the PUT if either is missing or altered), then call the complete endpoint to finalize the asset. Spends no credits.
Generate speech audio POST
Legacy synchronous text-to-speech compatibility endpoint for ElevenLabs and Cartesia. New integrations should use audio-generation via POST /processes plus GET /audio/voices so model capabilities, references, process polling, and output lineage match image/video generation. This endpoint still generates spoken audio from a script and stores it as a team audio asset (readable via GET /assets/{assetId} and listed by GET /assets). No polling — the response returns the finished asset. Pass a voiceId from a previous response to reuse a voice, or a voiceQuery (e.g. "warm female narrator") to pick one by description; omitting both uses a neutral narrator. The first 5,000 script characters per team per UTC day are free; characters beyond that bill team credits at 30 credits per 1,000 characters for ElevenLabs voices or 15 credits per 1,000 characters for Cartesia voices (403 insufficient_credits when the team balance cannot cover the request). The response reports creditsCharged and freeCharactersRemainingToday. Always send an Idempotency-Key: retries with the same key and body replay the original response (Idempotency-Replayed: true) instead of double-billing and double-generating; the same key with a different body returns idempotency_conflict.