{"openapi":"3.1.0","info":{"title":"Seedance 2.0 AI Public API","version":"1.0.0","description":"Generate AI videos and images with credits from the API key owner's personal balance. Submit a generation request, then poll GET /api/v1/tasks/{id} until the task is completed or failed.\n\nMedia URLs must be public https URLs. Do not send provider or teamSlug; the server picks the provider. To connect an AI assistant without writing API calls, see the MCP guide at https://www.seedance2ai.io/mcp."},"servers":[{"url":"https://www.seedance2ai.io"}],"externalDocs":{"description":"API documentation with examples","url":"https://www.seedance2ai.io/developers"},"tags":[{"name":"Video","description":"AI video generation"},{"name":"Image","description":"AI image generation"},{"name":"Tasks","description":"Task status and results"},{"name":"Account","description":"Balance and model catalogue"}],"paths":{"/api/v1/video/seedance2":{"post":{"tags":["Video"],"operationId":"generateSeedance2Video","summary":"Generate a Seedance 2.0 video","description":"Generate a 4–15 second video from text, a start image, or up to 12 image/video references.\n\nRules: image_url is required when mode=image-to-video; media_urls is required when mode=media-to-video. resolution 1080p-plus and 4k require quality_tier=pro.\n\nAccepted resolution labels depend on the account; the API documentation lists the values that apply to the key owner. Some quality tiers require a successful credits or plan purchase and otherwise return purchase_required (HTTP 403).\n\nWrite the prompt as concrete director instructions: subject, scene, action, camera movement, and order of events.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended on every POST. Once a request has created (and charged for) a task, a retry with the same key and the same body within 24 hours replays that response instead of creating a second paid task. Errors raised before anything was charged, such as insufficient_credits or service_busy, are not replayed, so after fixing the cause the same key runs the request again. Reusing a key with a different body, or while the first request is still running, returns idempotency_conflict (HTTP 409). Surrounding whitespace is trimmed; keys longer than 120 characters are ignored, which disables the protection.","schema":{"type":"string","minLength":1,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seedance2Request"}}}},"responses":{"202":{"description":"Task accepted. Poll GET /api/v1/tasks/{id} with the returned id (prefix sd2_) until status is completed or failed, and read the files from result_urls there.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubmitResponse"},{"type":"object","properties":{"id":{"type":"string","pattern":"^sd2_"},"model":{"type":"string","const":"seedance2"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceBusy"},"default":{"$ref":"#/components/responses/UnexpectedError"}}}},"/api/v1/video/seedance25":{"post":{"tags":["Video"],"operationId":"generateSeedance25Video","summary":"Generate a Seedance 2.5 video","description":"Generate a 4–30 second video, or pass duration \"auto\" to let the model choose the length. Accepts up to 30 reference images, 10 videos, and 10 audio clips (audio-only input is supported).\n\nRules: image_url is required when mode=image-to-video; media_urls is required when mode=media-to-video. Image-to-video follows the start frame's aspect ratio; editing or extending a video requires aspect_ratio=adaptive.\n\nAccepted resolution labels depend on the account: most accounts use 720p, 1080p and 1080p-plus. The API documentation lists the values that apply to the key owner, and a value the account cannot use returns HTTP 400 with allowed_resolutions.\n\nRequires a successful credits or plan purchase on the key owner's account; otherwise returns purchase_required (HTTP 403). With duration \"auto\", credits are reserved at the 30-second ceiling and the difference is refunded when the clip is ready.\n\nUse channel \"real\" when reference images or videos contain real people.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended on every POST. Once a request has created (and charged for) a task, a retry with the same key and the same body within 24 hours replays that response instead of creating a second paid task. Errors raised before anything was charged, such as insufficient_credits or service_busy, are not replayed, so after fixing the cause the same key runs the request again. Reusing a key with a different body, or while the first request is still running, returns idempotency_conflict (HTTP 409). Surrounding whitespace is trimmed; keys longer than 120 characters are ignored, which disables the protection.","schema":{"type":"string","minLength":1,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seedance25Request"}}}},"responses":{"202":{"description":"Task accepted. Poll GET /api/v1/tasks/{id} with the returned id (prefix sd2_) until status is completed or failed, and read the files from result_urls there.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubmitResponse"},{"type":"object","properties":{"id":{"type":"string","pattern":"^sd2_"},"model":{"type":"string","const":"seedance25"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceBusy"},"default":{"$ref":"#/components/responses/UnexpectedError"}}}},"/api/v1/video/kling4":{"post":{"tags":["Video"],"operationId":"generateKling4Video","summary":"Generate a Kling 4.0 video","description":"type reference-to-video covers text-only prompts and reference images, videos, subjects (elements), and voices. type keyframe-to-video interpolates between a first frame, optional middle frames, and a last frame.\n\nRules: at most 15 references in total and at most 5 videos per request; reference videos and video subjects together are capped at 30 seconds. A keyframe request allows at most duration + 1 frames, up to 10. Refer to references in the prompt by name (@image_1, @video_1, a subject's or voice's name, @first_frame, @keyframe_1, @last_frame); a mention that matches no reference is rejected before charging.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended on every POST. Once a request has created (and charged for) a task, a retry with the same key and the same body within 24 hours replays that response instead of creating a second paid task. Errors raised before anything was charged, such as insufficient_credits or service_busy, are not replayed, so after fixing the cause the same key runs the request again. Reusing a key with a different body, or while the first request is still running, returns idempotency_conflict (HTTP 409). Surrounding whitespace is trimmed; keys longer than 120 characters are ignored, which disables the protection.","schema":{"type":"string","minLength":1,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Kling4Request"}}}},"responses":{"202":{"description":"Task accepted. Poll GET /api/v1/tasks/{id} with the returned id (prefix sd2_) until status is completed or failed, and read the files from result_urls there.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubmitResponse"},{"type":"object","properties":{"id":{"type":"string","pattern":"^sd2_"},"model":{"type":"string","const":"kling4"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceBusy"},"default":{"$ref":"#/components/responses/UnexpectedError"}}}},"/api/v1/image/gpt-image-2-5":{"post":{"tags":["Image"],"operationId":"generateGptImage25","summary":"Generate images with GPT Image 2.5","description":"variant \"flare\" balances speed and quality; \"sunburst\" emphasizes fine detail and takes longer.\n\nRules: channel \"stable\" needs a fixed aspect_ratio (\"auto\" returns invalid_request). channel \"economy\" requires a successful credits or plan purchase; otherwise returns purchase_required (HTTP 403).","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended on every POST. Once a request has created (and charged for) a task, a retry with the same key and the same body within 24 hours replays that response instead of creating a second paid task. Errors raised before anything was charged, such as insufficient_credits or service_busy, are not replayed, so after fixing the cause the same key runs the request again. Reusing a key with a different body, or while the first request is still running, returns idempotency_conflict (HTTP 409). Surrounding whitespace is trimmed; keys longer than 120 characters are ignored, which disables the protection.","schema":{"type":"string","minLength":1,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GptImage25Request"}}}},"responses":{"202":{"description":"Task accepted. Poll GET /api/v1/tasks/{id} with the returned id (prefix gpt25_) until status is completed or failed, and read the files from result_urls there.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubmitResponse"},{"type":"object","properties":{"id":{"type":"string","pattern":"^gpt25_"},"model":{"type":"string","const":"gpt-image-2.5"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceBusy"},"default":{"$ref":"#/components/responses/UnexpectedError"}}}},"/api/v1/image/gpt-image-2":{"post":{"tags":["Image"],"operationId":"generateGptImage2","summary":"Generate images with GPT Image 2","description":"Generate one to four images from text or from one to ten reference images. When batch_count > 1 the response also returns batch_task_ids, batch_success, and batch_failed.\n\nRules: on the standard channel, aspect_ratio \"auto\" only supports resolution 1K and aspect_ratio 1:1 does not support 4K. On the economy channel, 4K requires an explicit aspect_ratio.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended on every POST. Once a request has created (and charged for) a task, a retry with the same key and the same body within 24 hours replays that response instead of creating a second paid task. Errors raised before anything was charged, such as insufficient_credits or service_busy, are not replayed, so after fixing the cause the same key runs the request again. Reusing a key with a different body, or while the first request is still running, returns idempotency_conflict (HTTP 409). Surrounding whitespace is trimmed; keys longer than 120 characters are ignored, which disables the protection.","schema":{"type":"string","minLength":1,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GptImage2Request"}}}},"responses":{"202":{"description":"Task accepted. Poll GET /api/v1/tasks/{id} with the returned id (prefix gpt2_) until status is completed or failed, and read the files from result_urls there.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubmitResponse"},{"type":"object","properties":{"id":{"type":"string","pattern":"^gpt2_"},"model":{"type":"string","const":"gpt-image-2"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceBusy"},"default":{"$ref":"#/components/responses/UnexpectedError"}}}},"/api/v1/image/nano-banana-pro":{"post":{"tags":["Image"],"operationId":"generateNanoBananaProImage","summary":"Generate images with Nano Banana Pro","description":"Image generation with accurate text rendering inside the image, from text or up to eight reference images.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended on every POST. Once a request has created (and charged for) a task, a retry with the same key and the same body within 24 hours replays that response instead of creating a second paid task. Errors raised before anything was charged, such as insufficient_credits or service_busy, are not replayed, so after fixing the cause the same key runs the request again. Reusing a key with a different body, or while the first request is still running, returns idempotency_conflict (HTTP 409). Surrounding whitespace is trimmed; keys longer than 120 characters are ignored, which disables the protection.","schema":{"type":"string","minLength":1,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NanoBananaProRequest"}}}},"responses":{"202":{"description":"Task accepted. Poll GET /api/v1/tasks/{id} with the returned id (prefix nbp_) until status is completed or failed, and read the files from result_urls there.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubmitResponse"},{"type":"object","properties":{"id":{"type":"string","pattern":"^nbp_"},"model":{"type":"string","const":"nano-banana-pro"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceBusy"},"default":{"$ref":"#/components/responses/UnexpectedError"}}}},"/api/v1/image/nano-banana-2":{"post":{"tags":["Image"],"operationId":"generateNanoBanana2Image","summary":"Generate images with Nano Banana 2","description":"Image generation from text or up to eight reference images. Set google_search to ground the image in current Google Search results.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended on every POST. Once a request has created (and charged for) a task, a retry with the same key and the same body within 24 hours replays that response instead of creating a second paid task. Errors raised before anything was charged, such as insufficient_credits or service_busy, are not replayed, so after fixing the cause the same key runs the request again. Reusing a key with a different body, or while the first request is still running, returns idempotency_conflict (HTTP 409). Surrounding whitespace is trimmed; keys longer than 120 characters are ignored, which disables the protection.","schema":{"type":"string","minLength":1,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NanoBanana2Request"}}}},"responses":{"202":{"description":"Task accepted. Poll GET /api/v1/tasks/{id} with the returned id (prefix nb2_) until status is completed or failed, and read the files from result_urls there.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubmitResponse"},{"type":"object","properties":{"id":{"type":"string","pattern":"^nb2_"},"model":{"type":"string","const":"nano-banana-2"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceBusy"},"default":{"$ref":"#/components/responses/UnexpectedError"}}}},"/api/v1/image/nano-banana-2-lite":{"post":{"tags":["Image"],"operationId":"generateNanoBanana2LiteImage","summary":"Generate images with Nano Banana 2 Lite","description":"Fast, lightweight image generation from text or up to ten reference images, for drafts and bulk runs.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended on every POST. Once a request has created (and charged for) a task, a retry with the same key and the same body within 24 hours replays that response instead of creating a second paid task. Errors raised before anything was charged, such as insufficient_credits or service_busy, are not replayed, so after fixing the cause the same key runs the request again. Reusing a key with a different body, or while the first request is still running, returns idempotency_conflict (HTTP 409). Surrounding whitespace is trimmed; keys longer than 120 characters are ignored, which disables the protection.","schema":{"type":"string","minLength":1,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NanoBanana2LiteRequest"}}}},"responses":{"202":{"description":"Task accepted. Poll GET /api/v1/tasks/{id} with the returned id (prefix nb2l_) until status is completed or failed, and read the files from result_urls there.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubmitResponse"},{"type":"object","properties":{"id":{"type":"string","pattern":"^nb2l_"},"model":{"type":"string","const":"nano-banana-2-lite"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceBusy"},"default":{"$ref":"#/components/responses/UnexpectedError"}}}},"/api/v1/image/seedream-5-pro":{"post":{"tags":["Image"],"operationId":"generateSeedream5ProImage","summary":"Generate images with Seedream 5 Pro","description":"channel \"economy\" balances quality and cost; \"standard\" has fewer content restrictions and costs more. Each reference image in image_urls adds 1 credit.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended on every POST. Once a request has created (and charged for) a task, a retry with the same key and the same body within 24 hours replays that response instead of creating a second paid task. Errors raised before anything was charged, such as insufficient_credits or service_busy, are not replayed, so after fixing the cause the same key runs the request again. Reusing a key with a different body, or while the first request is still running, returns idempotency_conflict (HTTP 409). Surrounding whitespace is trimmed; keys longer than 120 characters are ignored, which disables the protection.","schema":{"type":"string","minLength":1,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seedream5ProRequest"}}}},"responses":{"202":{"description":"Task accepted. Poll GET /api/v1/tasks/{id} with the returned id (prefix sd5p_) until status is completed or failed, and read the files from result_urls there.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubmitResponse"},{"type":"object","properties":{"id":{"type":"string","pattern":"^sd5p_"},"model":{"type":"string","const":"seedream-5-pro"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceBusy"},"default":{"$ref":"#/components/responses/UnexpectedError"}}}},"/api/v1/image/seedream-5-lite":{"post":{"tags":["Image"],"operationId":"generateSeedream5LiteImage","summary":"Generate images with Seedream 5 Lite","description":"channel \"standard\" balances quality and cost; \"wild\" has fewer content restrictions and costs more.","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended on every POST. Once a request has created (and charged for) a task, a retry with the same key and the same body within 24 hours replays that response instead of creating a second paid task. Errors raised before anything was charged, such as insufficient_credits or service_busy, are not replayed, so after fixing the cause the same key runs the request again. Reusing a key with a different body, or while the first request is still running, returns idempotency_conflict (HTTP 409). Surrounding whitespace is trimmed; keys longer than 120 characters are ignored, which disables the protection.","schema":{"type":"string","minLength":1,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seedream5LiteRequest"}}}},"responses":{"202":{"description":"Task accepted. Poll GET /api/v1/tasks/{id} with the returned id (prefix sd5l_) until status is completed or failed, and read the files from result_urls there.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SubmitResponse"},{"type":"object","properties":{"id":{"type":"string","pattern":"^sd5l_"},"model":{"type":"string","const":"seedream-5-lite"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/ServiceBusy"},"default":{"$ref":"#/components/responses/UnexpectedError"}}}},"/api/v1/tasks/{id}":{"get":{"tags":["Tasks"],"operationId":"getTask","summary":"Get a task's status and result","description":"Return the current state of a task created by the key owner. Poll every few seconds until status is completed or failed; result_urls then lists the output files. A failed task refunds its credits.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"The task id returned by a generation endpoint.","schema":{"type":"string","pattern":"^(sd2_|gpt25_|gpt2_|nbp_|nb2_|nb2l_|sd5p_|sd5l_)"}}],"responses":{"200":{"description":"The task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/tasks":{"get":{"tags":["Tasks"],"operationId":"listTasks","summary":"List recent tasks","description":"List the tasks the key owner created through the API in the last 30 days, newest first. Each item has the same shape as GET /api/v1/tasks/{id}.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"before","in":"query","required":false,"description":"The next_cursor value from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of tasks.","content":{"application/json":{"schema":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/balance":{"get":{"tags":["Account"],"operationId":"getBalance","summary":"Get the spendable credit balance","description":"credits is the total the key owner can spend through the API. subscription_credits is the part of that total that came from a plan and expires at subscription_credits_expire_at. Team credits are not used by the API.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The balance.","content":{"application/json":{"schema":{"type":"object","required":["credits","subscription_credits","subscription_credits_expire_at"],"properties":{"credits":{"type":"number"},"subscription_credits":{"type":"number"},"subscription_credits_expire_at":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/models":{"get":{"tags":["Account"],"operationId":"listModels","summary":"List the models the API serves","description":"Every model with its endpoint, accepted modes or types, and task id prefix.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The model catalogue.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Create an API key at https://www.seedance2ai.io/app/api."}},"responses":{"BadRequest":{"description":"invalid_request: bad JSON, an unsupported field, or a value outside the documented constraints. The message names the first failing field and details lists them all. Fix the request; retrying it unchanged fails again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"unauthorized: the API key is missing, invalid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientCredits":{"description":"insufficient_credits: the key owner's balance is too low. Some responses also include required_credits and available_credits. Add credits before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"purchase_required: the operation needs a successful credits or plan purchase. credits_frozen: credit spending is temporarily unavailable for this account; topping up does not lift it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"idempotency_conflict: the Idempotency-Key was used with a different body, or the first request with this key is still running. Use a new key for a new request; wait and retry for a running one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"rate_limited: submissions are limited to 30 per 60 seconds and reads to 120 per 60 seconds per account; Seedance requests that inspect reference media have a lower limit. Wait for Retry-After before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}},"NotFound":{"description":"not_found: the task does not exist or was not created by this key owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalError":{"description":"internal_error: an unexpected server failure. Retry with the same Idempotency-Key; contact support if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceBusy":{"description":"service_busy: a temporary generation or credit-concurrency issue. Retry with the same Idempotency-Key after a short delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnexpectedError":{"description":"Another structured error. Branch on error.code rather than the HTTP status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"Seedance2Request":{"type":"object","properties":{"mode":{"type":"string","enum":["text-to-video","image-to-video","media-to-video"],"default":"text-to-video"},"quality_tier":{"type":"string","enum":["mini","standard","pro"],"default":"standard"},"channel":{"type":"string","enum":["standard","real","wild"],"default":"standard"},"prompt":{"type":"string","minLength":3,"maxLength":10000},"aspect_ratio":{"type":"string","default":"16:9","enum":["1:1","21:9","4:3","3:4","16:9","9:16","adaptive"]},"duration":{"type":"string","enum":["4","5","6","7","8","9","10","11","12","13","14","15"],"default":"5"},"resolution":{"type":"string","enum":["480p","720p","1080p","1080p-plus","4k"],"default":"720p"},"image_url":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"end_image_url":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"media_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"maxItems":12},"generate_audio":{"type":"boolean","default":true},"fixed_lens":{"type":"boolean","default":false},"seed":{"type":"integer","minimum":-1,"maximum":4294967295}},"required":["prompt"],"additionalProperties":false},"Seedance25Request":{"type":"object","properties":{"mode":{"type":"string","enum":["text-to-video","image-to-video","media-to-video"],"default":"text-to-video"},"prompt":{"type":"string","minLength":3,"maxLength":10000},"channel":{"type":"string","enum":["standard","real","wild"],"default":"standard"},"aspect_ratio":{"type":"string","default":"16:9","enum":["1:1","21:9","4:3","3:4","16:9","9:16","adaptive"]},"duration":{"type":"string","enum":["auto","4","5","6","7","8","9","10","11","12","13","14","15","16","17","18","19","20","21","22","23","24","25","26","27","28","29","30"],"default":"5"},"resolution":{"type":"string","enum":["480p","720p","1080p","1080p-plus"],"default":"720p"},"image_url":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"end_image_url":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"media_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"maxItems":50},"generate_audio":{"type":"boolean","default":true}},"required":["prompt"],"additionalProperties":false},"Kling4Request":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"keyframe-to-video"},"prompt":{"type":"string","minLength":1,"maxLength":8000},"duration":{"type":"integer","minimum":3,"maximum":30,"default":5},"resolution":{"type":"string","enum":["720p","1080p"],"default":"720p"},"aspect_ratio":{"type":"string","enum":["auto","16:9","9:16","1:1","21:9"],"default":"auto"},"first_frame_url":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"keyframe_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"maxItems":8},"last_frame_url":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."}},"required":["type","prompt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"reference-to-video"},"prompt":{"type":"string","minLength":1,"maxLength":8000},"duration":{"type":"integer","minimum":3,"maximum":30,"default":5},"resolution":{"type":"string","enum":["720p","1080p"],"default":"720p"},"aspect_ratio":{"type":"string","enum":["auto","16:9","9:16","1:1","21:9"],"default":"auto"},"image_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"maxItems":10},"video_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"maxItems":5},"keep_original_sound":{"type":"boolean"},"elements":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"image_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"maxItems":4},"video_url":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"tag":{"type":"string","enum":["character","animal","prop","costume","scene","effect","others"]},"description":{"type":"string","maxLength":100},"voice_url":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."}},"required":["name"],"additionalProperties":false},"maxItems":7},"voices":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"audio_url":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."}},"required":["name","audio_url"],"additionalProperties":false},"maxItems":3}},"required":["type","prompt"],"additionalProperties":false}]},"GptImage25Request":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":20000},"variant":{"type":"string","enum":["flare","sunburst"],"default":"flare"},"aspect_ratio":{"type":"string","enum":["auto","1:1","3:2","2:3","4:3","3:4","16:9","9:16","21:9","27:16","16:27","9:8","8:9"],"default":"auto"},"resolution":{"type":"string","enum":["1K","2K","4K"],"default":"1K"},"channel":{"type":"string","enum":["standard","economy","stable"],"default":"standard"}},"required":["type","prompt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":20000},"variant":{"type":"string","enum":["flare","sunburst"],"default":"flare"},"aspect_ratio":{"type":"string","enum":["auto","1:1","3:2","2:3","4:3","3:4","16:9","9:16","21:9","27:16","16:27","9:8","8:9"],"default":"auto"},"resolution":{"type":"string","enum":["1K","2K","4K"],"default":"1K"},"channel":{"type":"string","enum":["standard","economy","stable"],"default":"standard"},"image_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"minItems":1,"maxItems":16}},"required":["type","prompt","image_urls"],"additionalProperties":false}]},"GptImage2Request":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":20000},"resolution":{"type":"string","enum":["1K","2K","4K"]},"aspect_ratio":{"type":"string","enum":["auto","1:1","5:4","9:16","21:9","16:9","4:3","3:2","4:5","3:4","2:3","2:1","1:2","3:1","1:3","9:21"]},"channel":{"type":"string","enum":["standard","economy"],"default":"standard"},"batch_count":{"type":"integer","minimum":1,"maximum":4,"default":1}},"required":["type","prompt","resolution","aspect_ratio"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":20000},"image_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"minItems":1,"maxItems":10},"resolution":{"type":"string","enum":["1K","2K","4K"]},"aspect_ratio":{"type":"string","enum":["auto","1:1","5:4","9:16","21:9","16:9","4:3","3:2","4:5","3:4","2:3","2:1","1:2","3:1","1:3","9:21"]},"channel":{"type":"string","enum":["standard","economy"],"default":"standard"},"batch_count":{"type":"integer","minimum":1,"maximum":4,"default":1}},"required":["type","prompt","image_urls","resolution","aspect_ratio"],"additionalProperties":false}]},"NanoBananaProRequest":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":10000},"image_size":{"type":"string","enum":["1:1","9:16","16:9","3:4","4:3","3:2","2:3","5:4","4:5","21:9","auto"],"default":"auto"},"output_format":{"type":"string","enum":["png","jpeg"],"default":"png"},"resolution":{"type":"string","enum":["1K","2K","4K"],"default":"1K"},"model":{"type":"string","const":"nano-banana-pro","default":"nano-banana-pro"}},"required":["type","prompt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":10000},"image_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"minItems":1,"maxItems":8},"image_size":{"type":"string","enum":["1:1","9:16","16:9","3:4","4:3","3:2","2:3","5:4","4:5","21:9","auto"],"default":"auto"},"output_format":{"type":"string","enum":["png","jpeg"],"default":"png"},"resolution":{"type":"string","enum":["1K","2K","4K"],"default":"1K"},"model":{"type":"string","const":"nano-banana-pro","default":"nano-banana-pro"}},"required":["type","prompt","image_urls"],"additionalProperties":false}]},"NanoBanana2Request":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":20000},"image_size":{"type":"string","enum":["1:1","1:4","1:8","2:3","3:2","3:4","4:1","4:3","4:5","5:4","8:1","9:16","16:9","21:9","auto"],"default":"auto"},"output_format":{"type":"string","enum":["png","jpeg"],"default":"png"},"resolution":{"type":"string","enum":["1K","2K","4K"],"default":"1K"},"google_search":{"type":"boolean","default":false},"model":{"type":"string","const":"nano-banana-2","default":"nano-banana-2"}},"required":["type","prompt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":20000},"image_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"minItems":1,"maxItems":8},"image_size":{"type":"string","enum":["1:1","1:4","1:8","2:3","3:2","3:4","4:1","4:3","4:5","5:4","8:1","9:16","16:9","21:9","auto"],"default":"auto"},"output_format":{"type":"string","enum":["png","jpeg"],"default":"png"},"resolution":{"type":"string","enum":["1K","2K","4K"],"default":"1K"},"google_search":{"type":"boolean","default":false},"model":{"type":"string","const":"nano-banana-2","default":"nano-banana-2"}},"required":["type","prompt","image_urls"],"additionalProperties":false}]},"NanoBanana2LiteRequest":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":20000},"aspect_ratio":{"type":"string","enum":["1:1","1:4","1:8","2:3","3:2","3:4","4:1","4:3","4:5","5:4","8:1","9:16","16:9","21:9","auto"],"default":"auto"},"model":{"type":"string","const":"nano-banana-2-lite","default":"nano-banana-2-lite"}},"required":["type","prompt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":20000},"image_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"minItems":1,"maxItems":10},"aspect_ratio":{"type":"string","enum":["1:1","1:4","1:8","2:3","3:2","3:4","4:1","4:3","4:5","5:4","8:1","9:16","16:9","21:9","auto"],"default":"auto"},"model":{"type":"string","const":"nano-banana-2-lite","default":"nano-banana-2-lite"}},"required":["type","prompt","image_urls"],"additionalProperties":false}]},"Seedream5ProRequest":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":3000},"aspect_ratio":{"type":"string","enum":["1:1","4:3","3:4","16:9","9:16","2:3","3:2"],"default":"1:1"},"resolution":{"type":"string","enum":["1K","2K"],"default":"1K"},"channel":{"type":"string","enum":["economy","standard"],"default":"economy"}},"required":["type","prompt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":3000},"aspect_ratio":{"type":"string","enum":["1:1","4:3","3:4","16:9","9:16","2:3","3:2"],"default":"1:1"},"resolution":{"type":"string","enum":["1K","2K"],"default":"1K"},"channel":{"type":"string","enum":["economy","standard"],"default":"economy"},"image_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"minItems":1,"maxItems":10}},"required":["type","prompt","image_urls"],"additionalProperties":false}]},"Seedream5LiteRequest":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":3000},"aspect_ratio":{"type":"string","enum":["1:1","4:3","3:4","16:9","9:16","2:3","3:2","21:9"],"default":"1:1"},"quality":{"type":"string","enum":["2K","4K"],"default":"2K"},"channel":{"type":"string","enum":["standard","wild"],"default":"standard"}},"required":["type","prompt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"image-to-image"},"prompt":{"type":"string","minLength":3,"maxLength":3000},"aspect_ratio":{"type":"string","enum":["1:1","4:3","3:4","16:9","9:16","2:3","3:2","21:9"],"default":"1:1"},"quality":{"type":"string","enum":["2K","4K"],"default":"2K"},"channel":{"type":"string","enum":["standard","wild"],"default":"standard"},"image_urls":{"type":"array","items":{"type":"string","format":"uri","pattern":"^https://","description":"A publicly reachable https URL. asset:// URLs are not accepted."},"minItems":1,"maxItems":10}},"required":["type","prompt","image_urls"],"additionalProperties":false}]},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","purchase_required","unauthorized","rate_limited","insufficient_credits","credits_frozen","idempotency_conflict","service_busy","internal_error","not_found"]},"message":{"type":"string"},"details":{"description":"Present on invalid_request: every failing field."}}}}},"SubmitResponse":{"type":"object","required":["id","status","model"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["processing","completed"],"description":"Usually processing. A channel that waits for the image inside the request returns completed; the task's result_urls are then ready at GET /api/v1/tasks/{id}."},"model":{"type":"string"},"credits_used":{"type":"number","description":"Credits charged for this task."},"remaining_credits":{"type":"number"}}},"Task":{"type":"object","required":["id","type","status","model","credits_used","credits_refunded","output","result_urls","error","created_at","updated_at"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["video","image"]},"status":{"type":"string","enum":["processing","completed","failed","unknown"],"description":"Poll while processing. completed and failed are final."},"model":{"type":"string"},"quality_tier":{"type":["string","null"]},"channel":{"type":["string","null"]},"resolution":{"type":["string","null"]},"credits_used":{"type":"number"},"credits_refunded":{"type":"number"},"pricing":{"type":["object","null"],"description":"Frozen pricing contract (Seedance 2.5 and Kling 4.0 tasks)."},"output":{"description":"Model-specific output; null until available. Prefer result_urls for the file links."},"result_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Every result file URL, flattened."},"error":{"type":["string","null"],"description":"Why the task failed, worded for API callers."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Model":{"type":"object","required":["id","name","type","method","endpoint","modes","task_id_prefix"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["video","image"]},"method":{"type":"string","const":"POST"},"endpoint":{"type":"string"},"modes":{"type":"array","items":{"type":"string"}},"task_id_prefix":{"type":"string"}}}}}}