Skip to main content

​
Base URL

https://api.yourouter.ai

​
Authentication

Include one of the following headers in every request:
  • Authorization: Bearer <YOUR_OUTER_API_KEY>
  • x-api-key: <YOUR_OUTER_API_KEY>
All requests should specify Content-Type: application/json. Every response returns an x-request-id header for tracing.

​
How It Works

  1. The client calls the gateway to create an Ark task using the same request body as the official Ark API.
  2. The gateway immediately returns the Ark-generated task ID and stores the task information (organization, model, Ark key, channel, status, etc.).
  3. The gateway polls Ark every 10 seconds using the saved Ark API key for tasks that are not yet complete.
  4. Billing reads usage.completion_tokens from successful results.
video_url in the response is a signed temporary URL from Ark. It is valid for 86,400 seconds (24 hours), so make sure to download the video before it expires.

​
Create a Task

Endpoint: POST /api/v3/contents/generations/tasks The request body matches Ark’s official API. Example: 
curl -X POST https://api.yourouter.ai/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUR_OUTER_API_KEY" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {
        "type": "text",
        "text": "Drone races through obstacles at high speed for an immersive flight experience  --resolution 1080p  --duration 5 --camerafixed false --watermark true"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_i2v.png" }
      }
    ]
  }'
Successful response (creation stage usually returns only the Ark task ID): 
{ "id": "cgt-20250906194036-2k4r4" }
The gateway stores this ID together with the model, organization, Ark key, channel, status, and starts background polling.

​
Query a Task

Endpoint: GET /api/v3/contents/generations/tasks/{id} Returns the task result from the gateway database. If the task is still generating, the response includes the current status. When finished, it returns Ark’s full result (with id and vendor injected). 
curl -X GET https://api.yourouter.ai/api/v3/contents/generations/tasks/cgt-20250906194036-2k4r4 \
  -H "Authorization: Bearer $YOUR_OUTER_API_KEY"
Running example: 
{ "id": "cgt-20250906194036-2k4r4", "status": "RUNNING" }
Completed example: 
{
  "id": "your-00000000000000000000000000000000",
  "model": "doubao-seedance-1-0-pro-250528",
  "status": "succeeded",
  "content": {
    "video_url": "https://ark-content-generation-cn-beijing.tos-cn-beijing.volces.com/doubao-seedance-1-0-pro/....mp4?...&X-Tos-Expires=86400&..."
  },
  "usage": {
    "completion_tokens": 246840,
    "total_tokens": 246840
  },
  "created_at": 1757158837,
  "updated_at": 1757158914,
  "seed": 95409,
  "resolution": "1080p",
  "duration": 5,
  "ratio": "16:9",
  "framespersecond": 24,
  "vendor": "Ark"
}

​
Billing

  • Usage is recorded only when status is succeeded.
  • usage.completion_tokens from the successful result is counted as text completion usage. The values mirror those returned by Ark.

​
Status Values

  • RUNNING – The gateway is polling Ark.
  • SUCCEEDED – Final result has been fetched and stored; queries return the full result.
  • NOT_FOUND – The gateway does not have this task ID (it may not exist or has been cleaned up).

​
Errors and Status Codes

  • 401/403 – Missing or invalid API key, organization disabled, or insufficient balance.
  • 200 + body – The query endpoint always returns HTTP 200; task status is conveyed in the JSON body.
  • 5xx – Internal server error or Ark is unavailable. Retry the request.

​
Usage Recommendations

  • Poll the task every 5–10 seconds. The gateway polls Ark every 10 seconds.
  • Preserve the x-request-id header from responses for troubleshooting.
  • If video_url expires, create a new task to obtain a fresh link (Ark does not currently support refresh).
  • Avoid creating the same content repeatedly; there is currently no idempotency key.
⌘I