> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ark Text-to-Video

> Generate videos with Ark's text-to-video API via YouRouter.

## Base URL

`https://api.yourouter.ai`

## Authentication

Include one of the following headers in every request:

* `Authorization: Bearer <YOUROUTER_API_KEY>`
* `x-api-key: <YOUROUTER_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:

```bash theme={null}
curl -X POST https://api.yourouter.ai/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUROUTER_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):

```json theme={null}
{ "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).

```bash theme={null}
curl -X GET https://api.yourouter.ai/api/v3/contents/generations/tasks/cgt-20250906194036-2k4r4 \
  -H "Authorization: Bearer $YOUROUTER_API_KEY"
```

**Running example**:

```json theme={null}
{ "id": "cgt-20250906194036-2k4r4", "status": "RUNNING" }
```

**Completed example**:

```json theme={null}
{
  "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.