API Guide | JoyToken | Documentation

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

Common API

Use JOY_TOKEN_API_BASE_URL from 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.

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

Choose a Protocol

OpenAI

Anthropic

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.

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.

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