Skip to navigation

API Guide

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

Common API

Use JOY_TOKEN_API_BASE_URL from Environments.

EndpointAuthenticationUse
GET /api/v1/modelsNonePublic model list
GET /api/v1/models/metaBearer or X-API-KeyCatalog filter metadata
GET /api/v1/pricingBearer or X-API-KeyCustomer-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.

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

Choose a Protocol

ItemValue
EndpointPOST /openai/v1/chat/completions
Base URLhttps://api.joytokens.ai/openai/v1
AuthenticationAuthorization: Bearer $JOY_TOKEN_API_KEY
Response bodychoices[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.

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.

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"
}'
{
"created": 1793395200,
"data": [
{
"url": "https://example.com/generated.png",
"revised_prompt": "A neon JoyToken logo on a black background"
}
]
}
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
}'

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):

StepEndpointNotes
Create generation taskPOST /openai/v1/videosText-to-video / image-to-video / first-and-last-frame, returns task_id (202)
Create editing taskPOST /openai/v1/videos/editsMulti-video stitching, same response as generation
Poll statusGET /openai/v1/videos/{task_id}200, shared by generation and editing tasks
Download videoGET /openai/v1/videos/{task_id}/content302 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).

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

FieldLocationUse
usageBodyToken statistics
metadata.billingBody / streaming metadataJoyToken billing details
X-Request-IDRequest headerLog and debugging correlation