One key across compatible protocols

Authentication

Send the 懂api key as a Bearer token. Never place it in the URL or request body.

Authorization: Bearer sk-your-key

Use Content-Type: application/json for JSON requests. For multipart image uploads, let the SDK or curl -F generate the Content-Type and boundary instead of applying a JSON header.

Routes

Live model catalog

This table reads model IDs, capabilities, endpoint types, and available groups from the live pricing contract.

Public machine-readable catalog: GET /api/geo/catalog. It contains only currently available model/group pairs and calculated public prices.

Use GET /api/geo/catalog/{product} for a product category and GET /api/geo/models/{model_id} for an exact model. Product values are gpt, claude, gemini, grok, kimi, image, video, and other.

Loading the live model catalog...

curl http://localhost:3000/v1/models \
  -H "Authorization: Bearer $DONGAPI_API_KEY"

POST /V1/CHAT/COMPLETIONS

Chat Completions

curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "Reply with ok"}],
    "stream": false
  }'

POST /V1/RESPONSES

Responses

Use this route only when the selected model lists Responses support.

curl http://localhost:3000/v1/responses \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","input":"Reply with ok"}'

POST /V1/MESSAGES

Anthropic Messages

curl http://localhost:3000/v1/messages \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Reply with ok"}]
  }'

POST /V1/IMAGES/GENERATIONS

Image generation

Use the direct host and choose dimensions supported by the current image model.

curl http://localhost:3000/v1/images/generations \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL_ID",
    "prompt": "A clean product photo on a white background",
    "size": "1024x1024",
    "n": 1
  }'

POST /V1/IMAGES/EDITS

Image editing

Use the direct host to upload a source image as multipart and describe the requested edit. Replace the model placeholder with a model available to your account that supports editing. Successful calls have been observed with gpt-image-2 in the GPT作图 group; when using this model, check that your key belongs to that group.

Public /v1 requests use the key's group for routing; do not send group in the body to switch groups. Successful image generation or an image capability label does not mean every model supports editing. JSON image URLs, masks, multiple images, and dimensions depend on the selected model.

curl http://localhost:3000/v1/images/edits \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -F "model=YOUR_IMAGE_MODEL_ID" \
  -F "prompt=Replace the background while preserving the product" \
  -F "image=@input.png" \
  -F "n=1"

Replace input.png with your local image path. curl -F generates multipart/form-data and its boundary automatically. Do not add Content-Type: application/json or set a boundary manually.

For 400, first check the image field, file, format, and model parameters. 502/503 usually indicates a service or upstream issue, not an invalid image format. Keep the request ID and error details for troubleshooting; avoid retrying in a loop without checking the cause.

ASYNCHRONOUS VIDEO TASKS

Video generation

Create a task, poll its ID with bounded backoff, then download the completed content.

curl http://localhost:3000/v1/videos \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_VIDEO_MODEL_ID","prompt":"A slow camera move"}'

curl http://localhost:3000/v1/videos/task_abc123 \
  -H "Authorization: Bearer $DONGAPI_API_KEY"

After status becomes completed, request GET /v1/videos/task_abc123/content. Stop polling on failed.

Grok video parameters

For groups publishing the Grok JSON contract, creation remains POST /v1/videos with JSON only. Upload reference images to public HTTP or HTTPS URLs first. The current model catalog's video_profile_by_group is authoritative.

Video second pricing uses the base rate for the selected mode and resolution, submitted duration, and current group multiplier, with no separate reference-image count charge. Check billing_mode=video_second, price_unit=second, and price_variants in the live catalog. Mode, resolution, duration, and rate freeze at submission and appear in Usage logs; polling does not charge tokens or a newer catalog rate.

Grok second rates follow the platform pricing rule: the USD numeric rate forms the CNY base at 1 USD = 1 CNY, then the group multiplier applies once. The official CNY reference uses approximately 1 USD = 7 CNY for comparison only. For example, a base rate of CNY P per second for 8 seconds at multiplier 0.6 costs P × 8 × 0.6 = 4.8P CNY; the current rate of each mode and resolution is on the Grok model page.

A Grok job accepted with a task ID that later returns the documented content moderation failure retains the site charge frozen at submission. Parameter validation failures and other errors do not imply this charge policy. Incomplete billing evidence keeps the reservation pending review.

1.5 without reference images generates with the base model. Add reference images to use 1.5 or 1080p. With one reference image, the video follows its aspect ratio; the ratio selection applies to text-only or multiple-image generation. 懂api accepts compatible references, reference_image_urls, and image_url inputs and compiles the correct image field. Reference audio/video, first/last frames, quality, seed, and other unpublished controls are outside this group's contract.

curl http://localhost:3000/v1/videos \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "prompt": "Slow camera push in while keeping the subject consistent",
    "duration": 8,
    "resolution": "480p",
    "image": {"url": "/YOUR_PUBLIC_IMAGE_PATH"}
  }'

Creation returns a 懂api task id. Poll GET /v1/videos/{id}, then download GET /v1/videos/{id}/content with the same API Key after completion. Keep API Keys on the server.

MiniMax-H3 video parameters

Use the MiniMax-H3 ID from the live model catalog in place of the placeholder. Create tasks with POST /v1/videos (JSON). The fields below are read at the top level or inside metadata; the top level wins when both are set.

Frames cannot be combined with reference images, videos or audio. Images may be https URLs or base64 data URIs; videos and audio must be public https URLs. Upload them first with POST /api/aigc/uploads (same API Key, form field file) and submit the signed URL it returns.

Billing is per second: the 768P per-second price of the request kind (text, frames or references) × duration × your group ratio, fixed at submission. The creation response's seconds is the billed duration; failed generations are refunded.

curl http://localhost:3000/v1/videos \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "prompt": "A red square glides from the left edge to the right",
    "duration": 6,
    "images": [
      "/YOUR_FIRST_FRAME_PATH",
      "/YOUR_LAST_FRAME_PATH"
    ]
  }'

Seedance 2.5 video parameters and billing

Seedance 2.5 models named with 480p, 720p or 1080p are billed per second at that resolution; models named with a duration (such as -30s) are billed per request. The live model catalog is authoritative for model IDs, groups and prices. Create tasks with POST /v1/videos (JSON or multipart), or call them in Volcengine Ark's own format through the Ark-compatible API below.

Invalid parameters fail at submission with 400 and nothing is reserved; param names the field, for example {"code":"invalid_request","message":"duration 须为整数秒，收到 4.5 (request id: …)","param":"duration"}.

In create and status responses, seconds is the output length and size the rendered frame size from Ark's official pixel table (480p 16:9 is 854x480, 720p 9:16 is 720x1280).

Billing follows Volcengine Ark's official rules: the per-second price depends on the resolution and on whether the request carries input video.

• Without reference video (text, reference images, reference audio): the no-video price × output seconds × your group ratio.
• With reference video: the with-video price × (output seconds + total reference video length) × your group ratio. Reference videos count at their actual length to the millisecond; a total under 4 seconds counts as 4 seconds.

Example: a 5-second 720p output with one 6-second reference video, at the with-video price of CNY 0.9072 per second and group ratio 1, costs 0.9072 × (5 + 6) = CNY 9.98; the same 5 seconds without reference video cost 1.512 × 5 = CNY 7.56. Current prices are in the live model catalog.

At submission the platform reads only the header of each reference video to get its length. If it cannot be read, the request fails with 400 and nothing is charged. The host must support HTTP Range requests (object storage and CDNs do); files uploaded to this site are read directly. Mode, resolution, output seconds, reference video length and price freeze at submission and appear in Usage logs; failed generations are refunded.

curl http://localhost:3000/v1/videos \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "prompt": "Follow the camera move of reference video 1, slowly pushing in on the coffee cup",
    "duration": 5,
    "reference_videos": ["SIGNED_REFERENCE_URL"]
  }'

Seedance billed by tokens (Volcengine Ark's official pricing)

Seedance 2.x models whose names carry no resolution (such as seedance-2-5) are billed by Volcengine Ark's own token price list: the price per million tokens depends on the output resolution and on whether the input has video, exactly as Ark lists it, times your group ratio. Call them with POST /v1/video/generations, POST /v1/videos or the Ark-compatible API below; the live model catalog is authoritative for model IDs, groups and current prices.

Billing:

• Tokens = (input video length + output length) × output width × output height × 24 / 1024, Ark's official formula; the charge is tokens × price ÷ 1,000,000 × your group ratio.
• At submission the requested resolution, ratio and length are reserved: an adaptive ratio (or no ratio with a first frame) reserves the largest frame of the resolution; -1 reserves the longest output (30 seconds for 2.5, 15 for 2.0); reference videos count at their measured length, with a total under 4 seconds counted as 4 seconds.
• When the video finishes it settles on the usage the task reports (usage.completion_tokens) and the rest of the reservation is refunded; the charge never exceeds the reservation. Without reported usage it settles on the official formula.
• Failures are free: a failed generation (including a moderation rejection) is refunded in full.

Example: Seedance 2.5 at 720p, 16:9, 5 seconds without reference video reserves 108,900 tokens × CNY 70 per million = CNY 7.623 (times your group ratio); if the task reports 100,000 tokens it settles at CNY 7.00 and CNY 0.623 is refunded. Usage logs show the price, the reserved tokens and the settlement basis.

Asset library (token-billed Seedance models)

Store a reference image, video or audio file in the asset library to get an asset ID, then reference it as asset://ASSET_ID wherever a media URL goes. Photos of real people are best sent this way: a plain URL may be refused by real-person screening. Records use Volcengine Ark's asset field names and the same Authorization: Bearer $DONGAPI_API_KEY. Import once, reuse: an asset stays available to every generation until you delete it.

• One library per model: an asset can only be used by the model it was imported for (see Models); import a file once for each model that needs it. Using it with another model fails with 400, at no charge, and says how to import it. Assets imported before this change belong to seedance-2-0-official; import them again for seedance-2-5.
• Status: Active is ready; Processing is refreshed in the background, usually to Active or Failed within a minute or two; for Failed, read FailReason.
• References: put asset://… where the URL would go: reference_image_urls, image_url.url / video_url.url / audio_url.url in metadata.content, reference_videos, or content[] of the Ark-compatible API. The asset type must match its field; images holds first and last frames, not references.
• Stored file: URL is this site's copy (http://localhost:3000/v1/assets/files/…), valid until the asset is deleted; the link is its own key, so keep it private. A URL import is downloaded here first; when this site cannot download it, your address is used and shown.
• Requirements: the model provider's rules apply. Images: jpeg, png, webp, bmp, tiff, gif, heic or heif, under 30 MB, aspect ratio 0.4–2.5, sides 300–6000 px. Videos: mp4 or mov, up to 50 MB, 2–30 s. Audio: mp3 or wav, 2–30 s. Direct file uploads do not take bmp or tiff yet; import those from a URL.
• Rejected imports: 400 asset_invalid at import, or Failed later, with the reason in message / FailReason. seedance-2-5 reasons carry the provider's error code (for example InputImageSensitiveContentDetected… for content review). For seedance-2-0-official the provider gives no reason, only the requirements; if those are all met, the content most likely failed review.
• Ownership: an asset belongs to the account that uploaded it; referencing another account's or a deleted asset fails with 400 at no charge. Asset IDs from other platforms or accounts cannot be used; import the files once to get IDs here.
• Billing: assets are free to upload and keep. A video asset counts at its measured length, like a video URL; image and audio assets do not change the price.
• Counts and rate: no per-account limit. A full library answers 429 asset_library_full (delete unused assets); busy uploads answer 429 asset_rate_limited (retry later). For many assets use the bulk import, about 15 a minute per model.
• Bulk import: the batch is checked first: an invalid item fails it with 400 and param naming the item (for example items[2].url), too little room with 429; nothing is queued then. Items import in order, retrying a busy upstream. An item is Queued or Importing, then carries its asset Id and status (Active / Processing / Failed, Deleted after deletion), or is Failed with Error.Code and Error.Message; resubmit just those. The batch is Running or Completed, with SucceededCount, FailedCount and PendingCount. Upload local files one at a time with POST /v1/assets.

curl http://localhost:3000/v1/assets \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "/YOUR_PERSON_IMAGE_PATH", "asset_type": "Image", "name": "front", "model": "YOUR_VIDEO_MODEL_ID"}'
# returns {"Id": "asset-…", "Status": "Processing", …}; use it once Active

curl http://localhost:3000/v1/video/generations \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "prompt": "The person in image 1 turns to face the camera",
    "metadata": {
      "content": [
        {"type": "image_url", "image_url": {"url": "asset://YOUR_ASSET_ID"}, "role": "reference_image"}
      ]
    }
  }'

curl http://localhost:3000/v1/assets/batch \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "items": [
      {"url": "/YOUR_PERSON_IMAGE_PATH", "asset_type": "Image", "name": "front"},
      {"url": "/YOUR_REFERENCE_VIDEO_PATH", "asset_type": "Video", "name": "motion"}
    ]
  }'
# Returns {"BatchId": "batch_…", "Status": "Running", "TotalCount": 2, "PendingCount": 2, "Items": [{"Index": 0, "Status": "Queued", …}, …]}

curl http://localhost:3000/v1/assets/batch/YOUR_BATCH_ID \
  -H "Authorization: Bearer $DONGAPI_API_KEY"
# When done: {"Status": "Completed", "SucceededCount": 2, "FailedCount": 0,
#   "Items": [{"Index": 0, "Status": "Active", "Id": "asset-…", …}, {"Index": 1, "Status": "Active", "Id": "asset-…", …}]}
# Reference asset://asset-… in every later generation; no need to import again

Volcengine Ark-compatible API (Seedance)

Code written for Volcengine Ark's video generation API can call Seedance here by changing only the base URL and key: use http://localhost:3000/api/v3 with Authorization: Bearer $DONGAPI_API_KEY, and set model to a Seedance model ID from this site. Requests share the /v1/videos pipeline, so billing, groups and Usage logs are the same.

The request body is Ark's, with these differences:

• content: text, image_url, video_url and audio_url items with role (first_frame, last_frame, reference_image, reference_video, reference_audio). Trailing --rs, --rt, --dur and --wm text parameters are read. Images and audio may be base64; videos must be public URLs. Token-billed models accept asset:// references to this site's asset library; per-second models do not. draft_task is not available.
• duration: a whole number from 4 to 30 (4 to 15 for Seedance 2.0), default 5 seconds. Token-billed models also accept -1 (a length the model chooses); per-second models do not.
• ratio: 16:9, 9:16, 1:1, 4:3 or 3:4. When omitted or adaptive, the ratio closest to the first frame image is used, otherwise 16:9. Token-billed models also accept 21:9 and keep adaptive, first and last frames in Ark's native form.
• resolution: optional; for per-second models it must match the resolution in the model ID, token-billed models accept any resolution of the model (default 720p).
• generate_audio and watermark apply; seed and camera_fixed are Seedance 1.0 options in Ark and are ignored by per-second models.
• Not available (400): return_last_frame, draft, callback_url, tools, frames, output_format=mov, service_tier=flex, video editing and extension (omni_reference_task_type edit / extend).

status is queued, running, succeeded, failed or expired. A succeeded task's content.video_url is a download link that needs no credentials: Ark's own official link, passed on unchanged when there is one (valid for 24 hours after the video is made, as on Ark), otherwise a signed link of this site. Download the video within 24 hours of its creation. Per-second models also return usage.completion_tokens, counted the Ark way (billed seconds × width × height × 24 / 1024); token-billed models return the tokens they were settled on, and a task with duration -1 reports its actual length once finished. Errors use Ark's format: {"error":{"code":"InvalidParameter","message":"…","param":"duration","type":"BadRequest"}}.

curl http://localhost:3000/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $DONGAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL_ID",
    "content": [
      {"type": "text", "text": "A kitten yawns at the camera"},
      {"type": "image_url", "image_url": {"url": "/YOUR_FIRST_FRAME_PATH"}, "role": "first_frame"}
    ],
    "duration": 5
  }'

import os
from arkruntime import Ark  # pip install --upgrade arkruntime

client = Ark(base_url="http://localhost:3000/api/v3", api_key=os.environ["DONGAPI_API_KEY"])
task = client.content_generation.tasks.create(
    model="YOUR_VIDEO_MODEL_ID",
    content=[{"type": "text", "text": "A kitten yawns at the camera"}],
    ratio="16:9",
    duration=5,
)
print(client.content_generation.tasks.get(task_id=task.id).status)