> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.joytokens.ai/llms.txt.

# API Guide

> How to use JoyToken public APIs

JoyToken exposes OpenAI-compatible and Anthropic-compatible model endpoints for developers.

## Common API

Use `JOY_TOKEN_API_BASE_URL` from [Environments](/user-guide/environments).

| Endpoint                  | Authentication        | Use                                   |
| ------------------------- | --------------------- | ------------------------------------- |
| `GET /api/v1/models`      | None                  | Public model list                     |
| `GET /api/v1/models/meta` | Bearer or `X-API-Key` | Catalog filter metadata               |
| `GET /api/v1/pricing`     | Bearer or `X-API-Key` | Customer-facing tier exchange pricing |

Model descriptions are localized with the optional `locale` query parameter. Use `locale=en` for English or `locale=zh` for Chinese. When omitted, JoyToken defaults to English.

```bash
curl -sS "https://api.joytokens.ai/api/v1/models?locale=en"
```

## Choose a Protocol

#### OpenAI

| Item           | Value                                      |
| -------------- | ------------------------------------------ |
| Endpoint       | `POST /openai/v1/chat/completions`         |
| Base URL       | `https://api.joytokens.ai/openai/v1`       |
| Authentication | `Authorization: Bearer $JOY_TOKEN_API_KEY` |
| Response body  | `choices[0].message.content`               |

Responses is available at `POST /openai/v1/responses`. Send `input` as a string or message input items; non-streaming text is returned in `output[0].content[0].text`.

```bash
curl -N -sS -X POST "https://api.joytokens.ai/openai/v1/responses" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "input": "Explain JoyToken in one sentence.",
    "instructions": "Be concise.",
    "max_output_tokens": 256,
    "stream": false
  }'
```

Image generation is available at `POST /openai/v1/images/generations`. `model` must be `auto` and `prompt` is required. Image options such as `n`, `size`, `quality`, `style`, and `response_format` are forwarded to the selected provider; omit provider-specific options unless every eligible image model supports them.

Image generation is non-streaming. Do not send `stream: true` or consume this endpoint as SSE: keep the request open until JoyToken returns one complete `application/json` response. Generated images are returned in `data`; use `data[0].url` or `data[0].b64_json` according to `response_format`.

```bash
curl -sS -X POST "https://api.joytokens.ai/openai/v1/images/generations" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: image-$(date +%s%3N)" \
  -d '{
    "model": "auto",
    "prompt": "A neon JoyToken logo on a black background",
    "n": 1,
    "size": "1024x1024"
  }'
```

```json
{
  "created": 1793395200,
  "data": [
    {
      "url": "https://example.com/generated.png",
      "revised_prompt": "A neon JoyToken logo on a black background"
    }
  ]
}
```

```bash
curl -N -sS -X POST "https://api.joytokens.ai/openai/v1/chat/completions" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: test-$(date +%s%3N)" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "Hello, help me test the gateway request path" }
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'
```

#### Anthropic

| Item           | Value                                   |
| -------------- | --------------------------------------- |
| Endpoint       | `POST /anthropic/v1/messages`           |
| Base URL       | `https://api.joytokens.ai/anthropic/v1` |
| Authentication | `x-api-key: $JOY_TOKEN_API_KEY`         |
| Response body  | `content[0].text`                       |

```bash
curl -N -sS -X POST "https://api.joytokens.ai/anthropic/v1/messages" \
  -H "x-api-key: $JOY_TOKEN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "Hello, help me test the gateway request path" }
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'
```

> **Warning**
>
> Do not send both `Authorization` and `X-API-Key` on the same request. If both are present, the current gateway reads `X-API-Key` first.

## Video Generation & Video Editing

The video endpoints use an asynchronous three-stage task model for `Doubao-Seedance-2.5` (omit `model` to use `auto` and let the gateway route within the video model pool):

| Step                   | Endpoint                                  | Notes                                                                          |
| ---------------------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
| Create generation task | `POST /openai/v1/videos`                  | Text-to-video / image-to-video / first-and-last-frame, returns `task_id` (202) |
| Create editing task    | `POST /openai/v1/videos/edits`            | Multi-video stitching, same response as generation                             |
| Poll status            | `GET /openai/v1/videos/{task_id}`         | 200, shared by generation and editing tasks                                    |
| Download video         | `GET /openai/v1/videos/{task_id}/content` | 302 redirect to the result URL                                                 |

The generation endpoint supports three modes: text-to-video (`prompt` only, required), image-to-video (`input_reference` as a single image or array, `prompt` optional), and first-and-last-frame (`first_frame` / `last_frame`, `prompt` optional). The generation endpoint does not accept `input_video`; use the editing endpoint for multi-video stitching. Editing requests must include at least one media input (`input_reference` / `first_frame` / `last_frame` / `input_video`).

```bash
curl -sS -X POST "https://api.joytokens.ai/openai/v1/videos" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "prompt": "A movie-style shot of an orange cat running through rainy Tokyo streets",
    "duration": 8,
    "size": "1280x720"
  }'
```

Task creation returns `{task_id, status, progress, model, created}`. Key parameters:

* `duration`: video length in seconds, continuous range of 2\~30, default 8, out-of-range values are clamped to the nearest bound; stitch longer videos through the editing endpoint
* `size`: `480p` / `720p` / `1080p` or `WIDTHxHEIGHT` (e.g. `1280x720`); aspect ratios support 16:9 and 9:16, use `parameters.aspect_ratio` for others
* `input_reference` / `first_frame` / `last_frame`: public image URLs, up to 30 images per request (combined), otherwise 400
* `parameters`: native upstream parameter passthrough (snake_case preferred, camelCase accepted), such as `aspect_ratio` / `resolution` / `duration_seconds` / `generate_audio` / `seed`; `fps`, `sample_count`, and 4K resolutions are not supported

Once `completed`, the response includes `result_url` (time-limited, download promptly or use `/content`), `duration`, and `completed_at`.

## Common Response Metadata

| Field              | Location                  | Use                           |
| ------------------ | ------------------------- | ----------------------------- |
| `usage`            | Body                      | Token statistics              |
| `metadata.billing` | Body / streaming metadata | JoyToken billing details      |
| `X-Request-ID`     | Request header            | Log and debugging correlation |