# HaryAI API: video (Seedance 2.5)

Video generation is an asynchronous task: submit, get a task id, poll until
it finishes, then download. Two formats are supported: Volcengine Ark (the
official Seedance format) and OpenAI Videos. Use the same API key as for
chat: `Authorization: Bearer <HARYAI_KEY>`. Get the key from
https://haryai.com/en/dashboard

## Models

| Model name | Resolutions | Duration |
|---|---|---|
| `dreamina-seedance-2-5-260628` | 480p, 720p, 1080p | up to 30 s |
| `dreamina-seedance-2-5-flash-261115` | 480p, 720p | up to 30 s |

Durations run from 4 to 30 seconds. Write `duration` (or `seconds`): without it the longest clip is held until the task finishes.

Video is paid from the balance only; a Coding Plan does not cover it.

## Ark format

Base URL: `https://api.haryai.com/api/v3`

### 1. Submit

```sh
curl https://api.haryai.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $HARYAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [{"type": "text", "text": "A cat dancing in the rain"}],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }'
```

Reply: `{"id": "<task id>"}`

- `model` and `content` (at least one item) are required. Add `image_url`
  or `video_url` items to `content` for image or video references.
- Other Ark fields (`duration`, `resolution`, `ratio`, `generate_audio`, …)
  are passed to Seedance unchanged. `resolution` must be one the model offers.
- Refused: `callback_url`, `draft: true`, `draft_task` items. Poll instead.

### 2. Poll

```sh
curl https://api.haryai.com/api/v3/contents/generations/tasks/<task id> \
  -H "Authorization: Bearer $HARYAI_KEY"
```

`status` is `queued`, `running`, `succeeded` or `failed`. Poll every few
seconds until it is `succeeded` or `failed`. Cancelled or expired tasks
show as `failed`. A failed task has `error: {code, message}`.

### 3. Download

On `succeeded`, `content.video_url` is the video. The link is on
`api.haryai.com`, needs no API key, and expires after 24 hours. Download it
before then.

```sh
curl -L -o video.mp4 "<content.video_url>"
```

`usage.completion_tokens` and `usage.total_tokens` show the billing tokens.

## OpenAI format

Base URL: `https://api.haryai.com/v1`

```sh
# 1. Submit (JSON or multipart)
curl https://api.haryai.com/v1/videos \
  -H "Authorization: Bearer $HARYAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"dreamina-seedance-2-5-260628","prompt":"A cat dancing in the rain","seconds":5,"size":"1280x720"}'

# 2. Poll
curl https://api.haryai.com/v1/videos/<id> -H "Authorization: Bearer $HARYAI_KEY"

# 3. Download (needs the key)
curl -L -o video.mp4 https://api.haryai.com/v1/videos/<id>/content \
  -H "Authorization: Bearer $HARYAI_KEY"
```

`size` is `WIDTHxHEIGHT`; the longer side picks the tier: 1920 or more is
1080p, 1280 or more is 720p, anything smaller is 480p.

- Fields: `prompt`, `seconds` (or `duration`; 1–3600 or -1), `size`,
  `metadata`. Reference images go in `input_reference`, `image` or
  `images[]`, as URLs (uploaded files are refused). Any other Ark field goes
  in `metadata`.
- `status` is `queued`, `in_progress`, `completed` or `failed`.

## Billing

- Billing tokens = (input video seconds + output seconds) × width × height
  × 24 / 1024. Reference images add nothing.
- On submit, the price is held from the balance. Without `duration` (or with
  -1), the hold is for 30 s, at the highest resolution if none is given; a
  low balance can then reject the request. Always set `duration`.
- When the task finishes the charge is settled to the real usage. A failed
  or timed-out task is refunded in full.
- Prices: https://haryai.com/en/seedance-api-pricing

## Errors

Key, model and balance errors use the chat shape
`{"error":{"message":"…","type":"new_api_error","code":"…"}}`:

| Status | Code | Meaning |
|---|---|---|
| 401 | (empty) | Missing or invalid key |
| 400 / 503 | `model_not_found` | Model not available to your account / not available now |
| 403 | `insufficient_user_quota` | Balance too low for the hold (set `duration` to lower it) |

After that, Ark-format errors are `{"error":{"code":"…","message":"…"}}`:

| Status | Code | Meaning |
|---|---|---|
| 400 | `InvalidParameter` | Bad field, e.g. an unsupported resolution or a refused field |
| 401 | `AuthenticationError` | |
| 403 | `AccessDenied` | |
| 404 | `NotFound` | Task not found (`Task not found`) |
| 429 | `RateLimitExceeded` | The model provider is busy; retry after a few seconds |
| 5xx | `InternalServiceError` | `Task request failed`; retry later |

Content moderation: the task ends `failed` with the upstream `error.code`
and `message`, and the hold is refunded. Change the prompt or the
reference and submit again.

A `/v1/videos` submit that fails returns a non-2xx status with an error
message; read the message, it names the field.

`/v1/videos/<id>/content` for an unknown task: 404
`{"error":{"message":"Task not found","type":"invalid_request_error"}}`.
