{"openapi":"3.1.0","servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API Key (sk-...)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}}},"Project":{"type":"object","description":"A piece of work. Tasks, files and canvases belong to one project.","required":["id","name","kind","role","canReceiveNewContent","inKeyScope","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["draft","standard"],"description":"`draft` is the person's own, one per organization and team."},"role":{"type":"string","enum":["view","edit","owner"]},"canReceiveNewContent":{"type":"boolean","description":"Whether this key can put new tasks and uploads here."},"inKeyScope":{"type":"boolean","description":"In the organization and team the key is bound to."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"GenerationModel":{"type":"object","description":"A generation model selectable in the SeedMaker web product. Pricing is expressed in SeedMaker credits.","required":["object","id","generationType","provider","name","description","isDefault","pricing","capabilities"],"properties":{"object":{"type":"string","const":"model"},"id":{"type":"string","description":"Exact value to pass as the model field when creating a task."},"generationType":{"type":"string","enum":["image","video"]},"provider":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"isDefault":{"type":"boolean"},"pricing":{"type":"object","description":"Image models expose creditsPerOutputImage. Video models expose creditsPerSecondAt720p plus resolution and mode multipliers.","additionalProperties":true},"capabilities":{"type":"object","description":"Supported modes, sizes or resolutions, ratios, duration limits, and optional features.","additionalProperties":true}}},"VideoTask":{"type":"object","description":"A video generation task.","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","submitted","running","succeeded","failed","cancelled"]},"mode":{"type":"string"},"model":{"type":"string"},"persistedVideoUrl":{"type":"string","nullable":true,"description":"Presigned download URL for the finished video. Expires in ~1h; re-GET the task for a fresh link. For an \"ogv\" task this is the .ogv."},"outputFormat":{"type":"string","enum":["mp4","ogv"],"description":"Container of the delivered video. An \"ogv\" request that fails to transcode is delivered as \"mp4\" with transcodeError = true."},"transcodeError":{"type":"boolean","description":"True when an \"ogv\" request was delivered as mp4 because transcoding failed."},"videoUrl":{"type":"string","nullable":true,"description":"Ephemeral upstream video URL; expires. Prefer persistedVideoUrl."},"videoDuration":{"type":"integer","nullable":true},"actualRatio":{"type":"string","nullable":true,"description":"Aspect ratio actually produced (may differ from the requested ratio)."},"creditCost":{"type":"string"},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true}}},"ImageTask":{"type":"object","description":"An image generation task.","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","submitted","running","succeeded","failed","cancelled"]},"mode":{"type":"string"},"model":{"type":"string"},"prompt":{"type":"string","nullable":true},"transparent":{"type":"boolean","description":"Whether automatic background removal was requested. When true, successful persistedImageUrls point to transparent PNGs."},"transparentCreditCost":{"type":"string","description":"Background-removal credits charged separately from creditCost. Settled per actual output image."},"persistedImageUrls":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Presigned download URLs for the finished images. Expire in ~1h; re-GET the task for fresh links."},"imageUrls":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Ephemeral upstream image URLs; expire. Prefer persistedImageUrls."},"actualRatio":{"type":"string","nullable":true,"description":"Aspect ratio actually produced (may differ from the requested ratio)."},"creditCost":{"type":"string"},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true}}},"VideoContentItem":{"description":"One part of a video task's multimodal `content` array.","oneOf":[{"type":"object","title":"Text","required":["type","text"],"properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","description":"Prompt text."}}},{"type":"object","title":"Image","required":["type","image_url"],"properties":{"type":{"type":"string","const":"image_url"},"image_url":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The storage `key` returned by POST /uploads, a public image URL, or an `asset://<id>` from POST /face/assets. Upload keys support automatic same-task portrait preparation."}}},"role":{"type":"string","enum":["first_frame","last_frame","reference_image"],"description":"`first_frame`/`last_frame` for image-to-video; `reference_image` for multimodal reference."}}},{"type":"object","title":"Video","required":["type","video_url","role","duration_ms"],"properties":{"type":{"type":"string","const":"video_url"},"video_url":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The storage `key` returned by POST /uploads/media/complete, or a public video URL."}}},"role":{"type":"string","enum":["reference_video"]},"duration_ms":{"type":"integer","minimum":1800,"maximum":30200,"description":"Exact clip duration in milliseconds. Seedance 2.0 accepts up to 15200 ms; Seedance 2.5 accepts up to 30200 ms (video_edit requires at least 4000 ms). SeedMaker also validates the combined reference-video duration against the selected model."}}},{"type":"object","title":"Audio","required":["type","audio_url","role","duration_ms"],"properties":{"type":{"type":"string","const":"audio_url"},"audio_url":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The storage `key` returned by POST /uploads/media/complete, or a public audio URL."}}},"role":{"type":"string","enum":["reference_audio"]},"duration_ms":{"type":"integer","minimum":1800,"maximum":30200,"description":"Exact clip duration in milliseconds. Seedance 2.0 accepts up to 15200 ms; Seedance 2.5 accepts up to 30200 ms. SeedMaker also validates the combined reference-audio duration against the selected model."}}}]},"ImageContentItem":{"description":"One part of an image task's multimodal `content` array.","oneOf":[{"type":"object","title":"Text","required":["type","text"],"properties":{"type":{"type":"string","const":"text"},"text":{"type":"string","description":"Prompt text (you can also use the top-level `prompt`)."}}},{"type":"object","title":"Image (reference)","required":["type","image_url"],"properties":{"type":{"type":"string","const":"image_url"},"image_url":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Public image URL, or an `asset://<id>` for a face asset."}}},"role":{"type":"string","enum":["reference_image"],"description":"Reference image for image edit / composition."}}},{"type":"object","title":"Image settings","required":["type"],"properties":{"type":{"type":"string","const":"image_settings"},"size":{"type":"string","description":"Output resolution, e.g. 1K / 2K / 4K."},"ratio":{"type":"string","description":"Aspect ratio, e.g. 1:1, 16:9."},"forceSingle":{"type":"boolean","description":"Disable sequential / grouped image generation."}}}]},"Upload":{"type":"object","properties":{"assetId":{"type":"string","format":"uuid","description":"Asset-library id (6h TTL until referenced by a task, then permanent)."},"key":{"type":"string","description":"Pass this as a content `image_url.url` to use the upload in a task."},"url":{"type":"string","description":"1-hour presigned download URL for previewing the upload."},"mimeType":{"type":"string"},"byteLength":{"type":"integer"},"contentEtag":{"type":"string","description":"Server-computed content identity for the exact uploaded bytes."},"width":{"type":"integer","nullable":true,"description":"Raster width read from the uploaded image header."},"height":{"type":"integer","nullable":true,"description":"Raster height read from the uploaded image header."}}},"BackgroundRemovalResult":{"type":"object","description":"A synchronous background-removal result. Only the input is persisted; the output is the original 24-hour AI MediaKit URL.","properties":{"inputKey":{"type":"string","description":"Storage key of the persisted input. It is not registered in the asset library."},"imageUrl":{"type":"string","description":"Direct AI MediaKit result URL. It expires after about 24 hours and is not persisted by Seedmaker."},"imageSize":{"type":"integer","nullable":true,"description":"Output size in bytes."},"imageFormat":{"type":"string","enum":["png","webp"]},"imageWidth":{"type":"integer","nullable":true},"imageHeight":{"type":"integer","nullable":true},"expiresAt":{"type":"integer","nullable":true,"description":"Provider result expiry as a Unix timestamp in seconds."},"creditCost":{"type":"number","enum":[0.01],"description":"Credits charged for this successful operation."}}},"Asset":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["image","video","audio","face"],"description":"`face` assets are portraits — reference them in task content via `volcAssetId`."},"subtype":{"type":"string","enum":["generated_image","generated_last_frame","generated_video","generated_audio"],"description":"Optional specialization. Generated images and last frames have type image; generated videos have type video."},"name":{"type":"string"},"url":{"type":"string","description":"Storage key / URL of the underlying file."},"volcAssetId":{"type":"string","nullable":true,"description":"For `face` assets: the `asset://<id>` URI to use as the content `image_url.url`. Null for ordinary assets."}}},"Credits":{"type":"object","properties":{"total":{"type":"number","description":"Kept for older clients. The same amount as `remaining`, or -1 when unlimited."},"used":{"type":"number","description":"Kept for older clients and always 0. It does not report past spending; read `creditCost` on each task."},"remaining":{"type":"number","nullable":true,"description":"What can be spent now. Null when unlimited."},"unlimited":{"type":"boolean"},"rpmLimit":{"type":"integer"},"apiKeyBudget":{"type":"object","nullable":true,"description":"This key's own budget in credits. Null when it has none.","properties":{"limit":{"type":"number"},"used":{"type":"number","description":"Net of refunds."},"remaining":{"type":"number"}}}}},"Eta":{"type":"object","nullable":true,"description":"Rough time-to-completion estimate from recent runs of the same parameters. A hint, not a guarantee; null when there is no signal yet.","properties":{"seconds":{"type":"integer","description":"Typical seconds until completion. Wait roughly this long before your first poll."},"maxSeconds":{"type":"integer","description":"Upper-bound seconds — most tasks finish within this."}}},"FaceGroup":{"type":"object","description":"A verified real-person face group (on-prem only).","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["pending_validate","ready"]}}},"FaceValidation":{"type":"object","description":"A started real-person liveness session (on-prem only).","properties":{"faceGroupId":{"type":"string","format":"uuid","description":"Poll GET /face/validations/{faceGroupId}, then ingest with this id."},"h5Link":{"type":"string","description":"URL the end user opens to complete liveness (120s validity)."}}}}},"externalDocs":{"description":"Agent guide (Markdown)","url":"https://seedmaker.tianlangedu.com.cn/api-doc.md"},"info":{"title":"Seedmaker API","version":"1.0.0","description":"Seedmaker Public API for AI video/image generation and asset management.\n\n## OpenAI Base URL\n\n```text\nhttps://seedmaker.tianlangedu.com.cn/api/openai/v1\n```\n\n[Agent guide (Markdown)](https://seedmaker.tianlangedu.com.cn/api-doc.md) | [Skills](https://seedmaker.tianlangedu.com.cn/mcp-skills)"},"tags":[{"name":"Models","description":"Generation models currently selectable in SeedMaker, with capabilities, descriptions, and credit pricing."},{"name":"Video","description":"Create, fetch and list video generation tasks."},{"name":"Image","description":"Create, fetch and list image generation tasks."},{"name":"Assets","description":"Asset library and uploads — ordinary reference media usable by plain URL / key in task content."},{"name":"Projects","description":"Projects group tasks, files and canvases. Without a project, new work goes to the key owner's draft."},{"name":"Face library","description":"Portrait preparation — explicit asset:// preflight plus the shared preparer used by video tasks after a synchronous input-image privacy rejection."},{"name":"Credits","description":"Credit balance."}],"paths":{"/models":{"get":{"summary":"List generation models","description":"List the image and video models selectable in SeedMaker, including exact IDs, descriptions, capabilities, and credit pricing. Requires `generation` scope.","tags":["Models"],"parameters":[{"name":"generationType","in":"query","schema":{"type":"string","enum":["image","video"]},"description":"Optional output-type filter."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/GenerationModel"}}}}}}},"400":{"description":"Invalid generationType","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos":{"get":{"summary":"List video tasks","description":"List recent video generation tasks. Requires `generation` scope.","tags":["Video"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VideoTask"}},"hasMore":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create video task","description":"Submit a video generation task. Requires `generation` scope. Credits are deducted immediately.\n\nFor reference images, prefer the storage `key` returned by `POST /uploads` as `image_url.url`. If Ark synchronously identifies a real-person/privacy input, SeedMaker prepares the owned upload through the portrait asset library and resubmits **the same task once**; no second task or second credit charge is created. If the image requires real-person verification, is persona/copyright restricted, or does not meet asset requirements, the same task fails with that disposition. Public HTTP URLs cannot use this automatic owned-upload fallback.\n\n`POST /face/assets` remains available as an optional explicit preflight, and an existing `asset://` value from `GET /assets?type=face` can be supplied directly.\n\nThe response includes an `eta` (estimated time to completion) — wait roughly `eta.seconds` before polling `GET /videos/{taskId}`.","tags":["Video"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mode","content"],"properties":{"mode":{"type":"string","enum":["text_to_video","image_first_frame","image_first_last_frame","multimodal_reference","video_edit","video_extend"],"description":"`text_to_video`; `image_first_frame` (one content image with role `first_frame`); `image_first_last_frame` (images with roles `first_frame` + `last_frame`); `multimodal_reference` / `video_edit` / `video_extend` (reference_image/video/audio)."},"content":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/VideoContentItem"},"description":"Multimodal parts (≥1): a `text` part for the prompt + any reference media. A stored `key` or `asset://<id>` must be one you can use: 403 REFERENCE_FORBIDDEN names the reference otherwise. A reference the model will refuse returns 400 VALIDATION_ERROR with its size and the requirement."},"model":{"type":"string","description":"Model id (required). Available models: `ep-20260327143137-pwdn2` (Seedance 2.0), `ep-20260808082334-nhjmj` (Seedance 2.5), `ep-20260327143210-qtvxd` (Seedance 2.0 Fast), `ep-20260625152214-vh6v2` (Seedance 2.0 Mini), `MiniMax-H3` (MiniMax H3), `MiniMax-H3-Highspeed` (MiniMax H3 Highspeed), `MiniMax-H3-Lite` (MiniMax H3 Lite), `MiniMax-H3-Max` (MiniMax H3 Max). Call GET /models for descriptions, capabilities, and current pricing."},"duration":{"type":"integer","minimum":4,"maximum":30,"description":"Requested video length in seconds. Seedance 2.0 supports 4–15; Seedance 2.5 supports 4–30. Seedance 2.5 video_edit determines output duration from its input video."},"resolution":{"type":"string","description":"Video resolution: `480p` or `720p` (default); Seedance 2.5 additionally supports `1080p`, and Seedance 2.0 supports `1080p` and `4k`. Read `/models` for the selected model."},"ratio":{"type":"string","description":"Video aspect ratio: `16:9` (default), `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, or `adaptive`. Seedance 2.5 first-frame, first-last-frame, edit, and extend modes always use `adaptive`."},"generateAudio":{"type":"boolean","description":"Generate audio. Defaults to true."},"watermark":{"type":"boolean"},"webSearch":{"type":"boolean","description":"Enable web search grounding for text-to-video. Defaults to false."},"isPrivate":{"type":"boolean","default":true,"description":"Keep the generation private (hidden from the org feed). Defaults to true for API tasks; pass false to make it org-visible. A task in a draft is always private."},"outputFormat":{"type":"string","enum":["mp4","ogv"],"default":"mp4","description":"Video container: `mp4` (default) or `ogv` (Ogg Theora/Vorbis)."},"projectId":{"type":"string","format":"uuid","description":"Project to put this in; you must be able to edit it. Optional; defaults to your draft. 403 PROJECT_NOT_AVAILABLE otherwise."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VideoTask"},"eta":{"$ref":"#/components/schemas/Eta"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"This would go over the API key's budget (API_KEY_BUDGET_EXCEEDED). Retrying will not help; the key's owner can raise the budget in Developer settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/{taskId}":{"get":{"summary":"Get video task","description":"Get the status and result of a video task. Poll until `status` is terminal (`succeeded` or `failed`); on success read `persistedVideoUrl`. Tip: wait about the `eta.seconds` returned by POST /videos before your first poll, then poll every 5–10s.","tags":["Video"],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VideoTask"}}}}}},"404":{"description":"Not found"}}}},"/images":{"get":{"summary":"List image tasks","description":"List recent image generation tasks. Requires `generation` scope.","tags":["Image"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ImageTask"}},"hasMore":{"type":"boolean"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create image task","description":"Submit an image generation task. Requires `generation` scope. Credits are deducted immediately.\n\nSet `transparent: true` to automatically remove the background from every generated output. The task completes only after durable transparent PNGs have been persisted; this adds **0.01 credits per output image** and is settled as a separate MediaKit operation against the actual output count. The task response reports this in `transparentCreditCost`, separate from the model generation `creditCost`.\n\n**Reference images containing people:** a portrait cannot be passed as a plain URL — the task will be rejected. Ingest it into the face library first (`POST /face/assets`), or reuse an existing one from `GET /assets?type=face`, then set that `volcAssetId` as the content item's `image_url.url`. Real-person ingestion is available on self-hosted instances only. Non-portrait references (objects, scenes, products) work as plain URLs.\n\nThe response includes an `eta` (estimated time to completion) — wait roughly `eta.seconds` before polling `GET /images/{taskId}`.","tags":["Image"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"mode":{"type":"string","enum":["text_to_image","image_edit"],"default":"text_to_image","description":"`text_to_image` (default) or `image_edit` (provide reference images in `content`)."},"prompt":{"type":"string","description":"Prompt text. You may also put it in a `content` text part."},"content":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ImageContentItem"},"description":"Multimodal parts (≥1): an `image_settings` part for size/ratio + any reference images. A stored `key` or `asset://<id>` must be one you can use: 403 REFERENCE_FORBIDDEN names the reference otherwise. A reference the model will refuse returns 400 VALIDATION_ERROR with its size and the requirement."},"model":{"type":"string","description":"Exact model id from GET /models?generationType=image. Optional; defaults to `doubao-seedream-5-0-260128`."},"resolution":{"type":"string","description":"Output resolution from the selected model in GET /models (e.g. `1K`, `2K`, `4K`). Defaults to `2K` for Seedream and `1K` for overseas models. Can also be set per `image_settings` content part."},"ratio":{"type":"string","description":"Aspect ratio, e.g. `1:1` (default), `16:9`. Can also be set per `image_settings` content part."},"watermark":{"type":"boolean"},"webSearch":{"type":"boolean","description":"Enable web search grounding. Defaults to false."},"transparent":{"type":"boolean","default":false,"description":"Automatically remove the background from every generated output and persist transparent PNGs. Adds 0.01 credits per actual output image."},"isPrivate":{"type":"boolean","default":true,"description":"Keep the generation private (hidden from the org feed). Defaults to true for API tasks; pass false to make it org-visible. A task in a draft is always private."},"projectId":{"type":"string","format":"uuid","description":"Project to put this in; you must be able to edit it. Optional; defaults to your draft. 403 PROJECT_NOT_AVAILABLE otherwise."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ImageTask"},"eta":{"$ref":"#/components/schemas/Eta"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"This would go over the API key's budget (API_KEY_BUDGET_EXCEEDED). Retrying will not help; the key's owner can raise the budget in Developer settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/images/remove-background":{"post":{"summary":"Remove an image background","description":"Synchronously remove the background from one base64-encoded image. Requires `generation` scope and costs **0.01 credits per successful call**; the charge is refunded automatically if storage or AI MediaKit processing fails. The input is persisted in org-isolated storage but never added to the asset library. The processed image is **not persisted**: `imageUrl` is AI MediaKit's direct result link and is valid for about 24 hours.\n\nScenes: `general` for unknown subjects, `human` for portraits, and `product` for products. Contour and crop options only take effect for `human` and `product`.","tags":["Image"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["base64","mimeType"],"properties":{"base64":{"type":"string","description":"Raw base64 image bytes without a data: prefix. Maximum decoded size: 10 MB."},"mimeType":{"type":"string","enum":["image/png","image/jpeg","image/webp","image/tiff","image/bmp","image/heic"]},"scene":{"type":"string","enum":["general","human","product"],"default":"general"},"needContour":{"type":"boolean","default":false,"description":"Add a contour. Only effective for human/product."},"contourColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","default":"#FFFFFF"},"contourSize":{"type":"integer","minimum":1,"maximum":100,"default":10},"needCropBackground":{"type":"boolean","default":false,"description":"Crop transparent padding to the subject. Only effective for human/product."},"outputFormat":{"type":"string","enum":["png","webp"],"default":"png","description":"Both formats preserve transparency."}}}}}},"responses":{"200":{"description":"Background removed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BackgroundRemovalResult"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"This would go over the API key's budget (API_KEY_BUDGET_EXCEEDED). Retrying will not help; the key's owner can raise the budget in Developer settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient credits or team scope required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Image exceeds 10 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"AI MediaKit or storage error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/images/{taskId}":{"get":{"summary":"Get image task","description":"Get the status and result of an image task. Poll until `status` is terminal (`succeeded` or `failed`); on success read `persistedImageUrls`. Tip: wait about the `eta.seconds` returned by POST /images before your first poll, then poll every 5–10s.","tags":["Image"],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ImageTask"}}}}}},"404":{"description":"Not found"}}}},"/assets":{"get":{"summary":"List assets","description":"List the organization's Seedmaker asset library. Requires `assets` scope. `type=face` lists already-ingested portrait assets (reference them via their `asset://` `volcAssetId`); other types are ordinary reference assets used by plain URL.","tags":["Assets"],"parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["image","video","audio","face"]}},{"name":"projectId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Only this project's files, including those other members made. Private records stay with their creator. 403 PROJECT_NOT_AVAILABLE if you cannot open it or it is outside this key's organization."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}}}}}}}}}},"/projects":{"get":{"summary":"List projects","description":"List the projects the key's owner can open: their draft first, their own in the key's organization or team, and any they were invited to or their team opened up. Pass a returned `id` as `projectId` when creating a task or registering an upload. Without `projectId`, new work goes to their draft. Requires `assets` scope.","tags":["Projects"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}}}}}}},"post":{"summary":"Create a project","description":"Create a project in the key's organization or team, with a first canvas. Only the key's owner can see it until they invite others. Without `name`, it is named automatically after it has been used. Requires `generation` scope.","tags":["Projects"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Optional; named automatically later when omitted."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Project"},{"type":"object","properties":{"canvasId":{"type":"string","format":"uuid","description":"The project's first canvas."}}}]}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key's owner cannot create projects here","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/face/assets":{"post":{"summary":"Prepare a portrait reference","description":"Explicitly prepare an owned upload in the portrait asset library and get back its `asset://` URI. This is an optional preflight; `POST /videos` uses the same preparer automatically when Ark synchronously returns an input-image privacy rejection for a storage `key`.\n\nRequires `assets` scope. Upload the image first via POST /uploads and pass the returned `key`. The key must resolve to an active image asset in the API key's organization and team scope.\n\n**Virtual portrait (default):** omit `faceGroupId`. Expected terminal dispositions are `REAL_PERSON_REQUIRED`, `PORTRAIT_RESTRICTED`, or `INVALID_PORTRAIT_ASSET`.\n\n**Real person (on-prem only):** pass a verified `faceGroupId` (from `POST /face/validations`). Returns `403 FACE_REAL_PERSON_DISABLED` when not available.","tags":["Face library"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"Storage key of an already-uploaded image (the `key` from POST /uploads)."},"name":{"type":"string","description":"Optional display name for the face asset."},"faceGroupId":{"type":"string","format":"uuid","description":"On-prem only: a verified real-person group to ingest into. Omit for virtual portraits."}}}}}},"responses":{"201":{"description":"Ingested","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"assetId":{"type":"string","format":"uuid"},"volcAssetId":{"type":"string","description":"The asset:// URI to use as a content image_url.url."}}}}}}}},"403":{"description":"Real-person ingestion is disabled (FACE_REAL_PERSON_DISABLED) — on-prem only."},"422":{"description":"Terminal portrait disposition: REAL_PERSON_REQUIRED, PORTRAIT_RESTRICTED, or INVALID_PORTRAIT_ASSET."},"502":{"description":"Portrait preparation is temporarily unavailable (PORTRAIT_PREPARATION_UNAVAILABLE)."}}}},"/face/validations":{"post":{"summary":"Start real-person verification","description":"**On-prem only.** Start a hosted liveness session for real-person verification and get back an `h5Link` the end user opens to complete liveness. Poll `GET /face/validations/{faceGroupId}` until status is `ready`, then ingest via `POST /face/assets` with `faceGroupId`. Requires `assets` scope. Available on self-hosted instances only; otherwise returns `403 FACE_REAL_PERSON_DISABLED`.","tags":["Face library"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":60,"description":"Name / note for the real person being verified."}}}}}},"responses":{"201":{"description":"Session started","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FaceValidation"}}}}}},"403":{"description":"Disabled (FACE_REAL_PERSON_DISABLED) — on-prem only."}}}},"/face/validations/{faceGroupId}":{"get":{"summary":"Poll verification status","description":"**On-prem only.** Poll a real-person validation: status is `pending_validate` until liveness completes, then `ready`. Requires `assets` scope. Returns `403 FACE_REAL_PERSON_DISABLED` on the public hosted service.","tags":["Face library"],"parameters":[{"name":"faceGroupId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending_validate","ready"]}}}}}}}},"403":{"description":"Disabled (FACE_REAL_PERSON_DISABLED) — on-prem only."},"404":{"description":"Group not found."}}}},"/face/groups":{"get":{"summary":"List real-person groups","description":"**On-prem only.** List the caller's ready (verified) real-person face groups, reusable for ingestion. Requires `assets` scope. Returns `403 FACE_REAL_PERSON_DISABLED` on the public hosted service.","tags":["Face library"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FaceGroup"}}}}}}},"403":{"description":"Disabled (FACE_REAL_PERSON_DISABLED) — on-prem only."}}}},"/uploads":{"post":{"summary":"Upload an image","description":"Upload a base64-encoded image and get back a storage `key`, preview `url`, server-computed `contentEtag`, and image dimensions. Requires `generation` scope. Max 12 MB; PNG / JPEG / WebP only.\n\nUse `key` (not the expiring preview `url`) as a video task's `image_url.url` to enable automatic same-task portrait preparation after a synchronous Ark privacy rejection. You may also call POST /face/assets explicitly before creating the task.\n\nThe upload is kept for 6 hours unless referenced by a task, after which it becomes a permanent asset visible in `GET /assets`.","tags":["Assets"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["base64","mimeType"],"properties":{"base64":{"type":"string","description":"Base64-encoded image bytes (no data: prefix)."},"mimeType":{"type":"string","enum":["image/png","image/jpeg","image/webp"]},"category":{"type":"string","description":"Optional category label; defaults to \"uploads\"."},"projectId":{"type":"string","format":"uuid","description":"Project to put this in; you must be able to edit it. Optional; defaults to your draft. 403 PROJECT_NOT_AVAILABLE otherwise."},"folderId":{"type":"string","format":"uuid","description":"Folder of that project. Optional; defaults to its root."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Upload"}}}}}},"413":{"description":"Payload too large"},"415":{"description":"Unsupported media type"}}}},"/uploads/media":{"post":{"summary":"Request a direct file upload","description":"Get a temporary URL for uploading an image, video or audio file directly to storage. PUT the file bytes to `uploadUrl` with the returned `headers`, then call POST /uploads/media/complete. Requires `generation` scope. PNG, JPEG and WebP images, MP4 and MOV video, and MP3 and WAV audio, up to 5 GB each. Using a file as a reference has its own limit from the model, checked when the task is created: 30 MB per image for Seedance, 50 MB for other image models, 200 MB per video, 15 MB per audio file.","tags":["Assets"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","contentType","sizeBytes"],"properties":{"type":{"type":"string","enum":["image","video","audio"]},"contentType":{"type":"string","enum":["image/png","image/jpeg","image/webp","video/mp4","video/quicktime","audio/mpeg","audio/wav"]},"sizeBytes":{"type":"integer","minimum":1,"description":"File size in bytes, up to 5 GB. A model has its own, smaller limit, checked when the file is used as a reference."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"assetId":{"type":"string","format":"uuid"},"uploadUrl":{"type":"string","description":"Temporary storage URL."},"method":{"type":"string","const":"PUT"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers the PUT must send."},"expiresInSeconds":{"type":"integer"}}}}}}}},"400":{"description":"Invalid input"},"413":{"description":"File too large"},"415":{"description":"Unsupported media type"}}}},"/uploads/media/complete":{"post":{"summary":"Register a directly uploaded file","description":"Register a file after it has been PUT to `uploadUrl`. Use the returned `key` as a task's `image_url.url`, `video_url.url` or `audio_url.url`. Video and audio need `durationMs`, sent as `duration_ms`, and mode `multimodal_reference`. Uploads no task uses are removed after 6 hours. Requires `generation` scope.","tags":["Assets"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assetId","type","contentType"],"properties":{"assetId":{"type":"string","format":"uuid","description":"`assetId` from POST /uploads/media."},"type":{"type":"string","enum":["image","video","audio"]},"contentType":{"type":"string","enum":["image/png","image/jpeg","image/webp","video/mp4","video/quicktime","audio/mpeg","audio/wav"]},"durationMs":{"type":"integer","minimum":1,"description":"Exact duration in milliseconds. Required for video and audio."},"width":{"type":"integer","minimum":1,"description":"Width in pixels."},"height":{"type":"integer","minimum":1,"description":"Height in pixels."},"name":{"type":"string","maxLength":200,"description":"Display name in the asset library."},"projectId":{"type":"string","format":"uuid","description":"Project to put this in; you must be able to edit it. Optional; defaults to your draft. 403 PROJECT_NOT_AVAILABLE otherwise."},"folderId":{"type":"string","format":"uuid","description":"Folder of that project. Optional; defaults to its root."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"assetId":{"type":"string","format":"uuid"},"key":{"type":"string","description":"Storage key to use as `image_url.url`, `video_url.url` or `audio_url.url`."},"type":{"type":"string","enum":["image","video","audio"]},"url":{"type":"string","description":"One-hour preview URL."},"mimeType":{"type":"string"},"durationMs":{"type":["integer","null"]},"sizeBytes":{"type":["integer","null"]}}}}}}}},"400":{"description":"Invalid input"},"409":{"description":"The file has not been uploaded yet"},"415":{"description":"Unsupported media type"}}}},"/credits":{"get":{"summary":"Get credit balance","description":"Get current credit balance for this API key's user, and this key's own budget if it has one. Requires `credits` scope.","tags":["Credits"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Credits"}}}}}}}}},"/api/openai/v1/models":{"servers":[{"url":"/"}],"get":{"operationId":"listChatModels","tags":["Chat Completions"],"summary":"List public chat models","responses":{"200":{"description":"Use data[].id in a completion request.","content":{"application/json":{"schema":{"type":"object","required":["object","data"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"type":"object","required":["id","object","owned_by","created"],"properties":{"id":{"type":"string"},"object":{"const":"model"},"owned_by":{"type":"string"},"created":{"type":"integer"}}}}}}}}},"default":{"description":"OpenAI-compatible error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type","param","code"],"properties":{"message":{"type":"string"},"type":{"type":"string"},"param":{"type":["string","null"]},"code":{"type":"string"}}}}}}}}}}},"/api/openai/v1/chat/completions":{"servers":[{"url":"/"}],"post":{"operationId":"createChatCompletion","tags":["Chat Completions"],"summary":"Create a chat completion","description":"Configure the OpenAI client base URL as /api/openai/v1 on this host. Use a SeedMaker key with generation scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"model":{"type":"string"},"messages":{"minItems":1,"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","developer","user","assistant","tool"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"image_url"},"image_url":{"type":"object","properties":{"url":{"type":"string","pattern":"^(https?:\\/\\/|data:image\\/[a-z0-9.+-]+;base64,)"},"detail":{"type":"string","enum":["auto","low","high"]}},"required":["url"]}},"required":["type","image_url"]}]}},{"type":"null"}]},"tool_call_id":{"type":"string"},"tool_calls":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"function"},"function":{"type":"object","properties":{"name":{"type":"string"},"arguments":{"type":"string"}},"required":["name","arguments"]}},"required":["id","type","function"]}},"reasoning_content":{"type":["string","null"]},"encrypted_content":{"type":["string","null"]},"name":{"type":"string"}},"required":["role"],"additionalProperties":false}},"stream":{"type":"boolean"},"stream_options":{"type":"object","properties":{"include_usage":{"type":"boolean"}}},"n":{"type":"number","const":1},"temperature":{"type":"number"},"top_p":{"type":"number"},"max_tokens":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"max_completion_tokens":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"stop":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}]},"seed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"presence_penalty":{"type":"number"},"frequency_penalty":{"type":"number"},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"function"},"function":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"strict":{"type":["boolean","null"]}},"required":["name"]}},"required":["type","function"]}},"tool_choice":{"anyOf":[{"type":"string","enum":["auto","none","required"]},{"type":"object","properties":{"type":{"type":"string","const":"function"},"function":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]}},"required":["type","function"]}]},"parallel_tool_calls":{"type":"boolean"},"response_format":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"user":{"type":"string"},"reasoning_effort":{"type":"string"},"thinking":{"type":"object","properties":{"type":{"type":"string","enum":["enabled","disabled","auto"]}},"required":["type"]}},"required":["model","messages"],"additionalProperties":false},"example":{"model":"deepseek-v4-1-flash-261017","messages":[{"role":"user","content":"Hello"}]}}}},"responses":{"200":{"description":"With stream=true, process data frames through [DONE].","headers":{"x-request-id":{"description":"SeedMaker request ID for usage support","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["id","model","choices"],"properties":{"id":{"type":"string"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"message":{"type":"object"},"finish_reason":{"type":["string","null"]}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}}},"text/event-stream":{"schema":{"type":"string"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type","param","code"],"properties":{"message":{"type":"string"},"type":{"type":"string"},"param":{"type":["string","null"]},"code":{"type":"string"}}}}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Wait in seconds, when provided"}}},"default":{"description":"OpenAI-compatible error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type","param","code"],"properties":{"message":{"type":"string"},"type":{"type":"string"},"param":{"type":["string","null"]},"code":{"type":"string"}}}}}}}}}}}}}