Wokey API Documentation

One API key and one base URL, compatible with OpenAI and Anthropic request formats. Connect Claude Code, Codex, and other clients in minutes.

Create API KeykeyView Modelsview_list
verified

Official upstream, verifiable

Requests go to each vendor’s official API. On the raw passthrough path, responses can carry a signed proof you can check offline yourself.

1

Official upstream

Requests go to the model vendor’s official API, for example api.anthropic.com for Claude. The model you pick on the model page is the model you get, with no silent substitution.

2

Verifiable

Turn on official-direct verification for a key and raw passthrough responses carry a tee.proof signed inside an AWS Nitro Enclave. The open-source verifier checks the upstream host and response bytes locally, with no trust in Wokey required.

3

Pay per use

One API key for every model, billed per token actually used. Prices follow the public model pages, and every call’s billing detail is on the API page.

rocket_launch

Quick Start

Prepare an API key and send one request to verify the gateway and model.

1

Create an account and key

Go to the API page and create an API key. The full key is shown once, so copy it immediately.

2

Configure the Base URL

Use https://api.wokey.ai. The gateway accepts paths with and without /v1, so clients that expect https://api.wokey.ai/v1, such as the OpenAI SDK, work either way. What breaks is a doubled /v1: Claude Code appends /v1/messages itself, so a base URL ending in /v1 becomes /v1/v1/messages and returns 404. Never use the page origin or localhost.

3

Send the first request

Put the key in the auth header expected by your client, choose an available model ID, and send a request.

vpn_key

API Key Integration

Use the API key on public requests: Bearer for OpenAI clients, x-api-key for Anthropic/Claude Code.

Header format

Public endpoints accept Authorization: Bearer YOUR_API_KEY and the Anthropic-standard x-api-key: YOUR_API_KEY. If both headers are sent, they must contain the same key.

Key safety

Do not ship keys in browser code, public repositories, client bundles, or logs.

Key management

Use the API page to create, pause, rename, and delete keys, and to inspect usage records.

Hosted credentials

When hosted credentials are enabled, that key only uses your credentials and does not fall back to the public pool.

api

API Endpoints

Wokey exposes standard compatibility endpoints.

POST/chat/completions

OpenAI Chat Completions-compatible format for most OpenAI SDKs and chat clients.

POST/responses

OpenAI Responses-compatible format. Recommended for Codex CLI.

POST/messages

Anthropic Messages-compatible format for Claude Code and Anthropic SDKs. Native Messages requests must include max_tokens; use /chat/completions for OpenAI-style requests.

POST/images/generations

OpenAI Images-compatible format for gpt-image-2.5. Unlike text APIs, image requests use separate size, response, and per-image billing rules described below.

POST/v1/videos

Asynchronous video generation. Submission returns a job ID; poll the status endpoint and download the finished video as described below.

GET/models

Returns available text models by default. Use output_modalities=image, video, or all to discover currently callable media models.

GET/v1/models/pricing

Returns normalized pricing for currently callable text, image, and video models, filterable by output modality or exact model ID.

GET/v1/images/models

Returns currently callable image models with supported parameters, dimension limits, and per-image pricing tiers.

GET/v1/videos/models

Returns video models with at least one sellable variant, including modes, resolutions, durations, aspect ratios, and per-second prices.

The gateway also supports /v1/chat/completions, /v1/responses, /v1/messages, /v1/images/generations, and /v1/models paths. Video generation uses /v1/videos.

Image Generation API

Sync JSON / optional async

/images/generations supports custom aspect ratios. The platform validates and reserves balance from the requested size, then settles against the actual output image dimensions after success.

brushNo code needed — try it in your browser with Image Studioarrow_forward

Quick examples

Returns data[0].b64_json. Image edits use the image file field; async mode returns a job ID.

cURL
curl https://api.wokey.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5",
    "prompt": "A quiet lake at sunrise",
    "size": "1536x1024"
  }'
Full parameters, pricing, and FAQexpand_more
Async optionFor slower generations, add the request headerPrefer: respond-async· Job ID → poll status → download image

Request parameters

ParameterRequiredDescription
modelRequiredCurrently gpt-image-2.5 is supported; legacy alias gpt-image-2 is also accepted.
promptRequiredNon-empty image prompt.
sizeOptionalWIDTHxHEIGHT, including non-square aspect ratios; each side must be 128-4096 px. Omitted or auto defaults to 1024x1024.
nOptionalOnly 1 is currently supported. Omitted requests are treated as 1.
streamOptionalSet true for the official OpenAI image streaming protocol over SSE: progressive previews arrive as image_generation.partial_image events and the final image as image_generation.completed. Billing matches the non-streaming path; preview frames are free.
partial_imagesOptionalNumber of progressive preview frames when streaming, integer 0-3 (default 0: only the final event).

Response parameter: data[0].b64_json contains the generated image base64.

Tiers and billing

Tiers are based on the image longest side. Requested size determines the upfront reserve; final billing uses the actual output image longest side.

TierActual output longest sideReserved by requested sizePrice
1K<= 1280 pxRequested longest side <= 1280 px$0.01 / image
2K1281-2048 pxRequested longest side 1281-2048 px$0.01 / image
4K2049-4096 pxRequested longest side 2049-4096 px$0.01 / image

FAQ

What is the "Studio 网页生图" key in my key list? Can I delete it?

After you use Image Studio, the platform manages a hidden API key named "Studio 网页生图" for you (early users may see "网页生图"). Every Studio turn bills through it on the exact same accounting and rate-limit path as API calls, which is why request records attribute those calls to that key name. Its secret is never sent to the browser. Deleting or pausing it is harmless — the next Studio turn recreates it automatically.

How is Image Studio billed?

Identically to the API: per image, by actual output size tier, deducted from your account balance. Spend shows up in your usage summary and request records; there is no separate pricing.

Where are Studio images stored?

Only in your current browser. The platform does not store generated images, so switching browsers or clearing site data loses the history — download anything you want to keep.

Video Generation API

Async job

/v1/videos is an asynchronous job API. The platform reserves the job cost when it accepts the request and returns a job ID; poll that job until completion, then download the finished MP4.

movieNo code needed — try Video Studio in your browserarrow_forward

Quick examples

The request returns 202 and a job ID; download the MP4 from content_url when complete.

cURL
curl https://api.wokey.ai/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: video-demo-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jimeng-seedance-2.0-mini",
    "prompt": "A paper boat drifting through a neon-lit rainy street, cinematic tracking shot",
    "duration_seconds": 5,
    "ratio": "16:9",
    "video_resolution": "720p"
  }'
Full parameters, lifecycle, and pricingexpand_more

Create-job parameters

ParameterRequiredDescription
modelRequiredVideo model ID, such as jimeng-seedance-2.0-mini. Use the live Video Studio catalog for currently available model, resolution, and duration combinations.
promptRequiredNon-empty video prompt.
duration_secondsRequiredInteger duration in seconds. Each model and pricing SKU has its own allowed range. duration is also accepted.
ratioRequiredAspect ratio: 1:1, 3:4, 4:3, 9:16, 16:9, or 21:9.
video_resolutionRequiredModel-dependent output resolution, currently one of 480p, 720p, 1080p, or 4k. resolution is also accepted.
modeOptionalDefaults to text_to_video. Model-dependent alternatives are image_to_video, first_last_frames, and multimodal_reference. Use multipart/form-data when sending media inputs.
image / first_frame / last_frame / video / audioConditionalMultipart fields for media modes. image_to_video requires one image; first_last_frames requires one frame in each field; multimodal_reference accepts up to 9 images, 3 videos, and 3 audio files.
Idempotency-KeyRecommendedRequest header containing 8-160 safe characters. Reuse the same key after a network timeout to avoid duplicate jobs and reservations.

Job lifecycle

Do not keep the create request open while waiting for the video. Persist the job ID and poll at a reasonable interval until status becomes completed, failed, or cancelled.

POST/v1/videos
Create job

Returns HTTP 202 and object: "video". The initial status is in_progress.

GET/v1/videos/{id}
Get status

Returns job parameters, status, price, error details, and content_url. While queued upstream it also returns queue.position, queue.length, and the suggested next query time next_poll_at.

GET/v1/videos/{id}/content
Download video

Returns video/mp4 after completion. Download promptly; files are not retained forever.

GET/v1/videos?limit=20
List jobs

Lists video jobs for the current account, with limit and before pagination.

DELETE/v1/videos/{id}
Cancel or delete

Cancels a queued job or deletes retained content from a completed job. A job cannot be force-canceled after upstream generation starts.

price_usd is the reserved or settled amount for this job. After completion, content_url points to a download route that requires the same API-key authentication. A null queue means no validated upstream position is currently available; it does not mean the job failed.

Billing

Video is priced by model, resolution, and duration: total price = current per-second rate × duration_seconds. The amount is reserved when the job is created and settled on success; a failed job or a job canceled before submission releases the reservation. Current rates and active SKUs are shown live on the API Access page and in Video Studio.

  • Video jobs can take several minutes. Persist the job ID and use polling backoff in production.
  • Reuse the original Idempotency-Key when retrying a create request. The same key cannot be reused with different parameters.
  • Download finished videos promptly. After content is deleted, content_url is no longer available.

Balance, Request Records, and Usage

These endpoints query the current API key, using either Bearer or x-api-key. Production API keys are isolated by key id: requests made with key A do not appear when querying with key B, even when both keys belong to the same account. Request records only accept page; the server fixes page size at 20 records.

GET/v1/dashboard/balance

Account Balance

Returns the account-level balance for the account that owns the current API key. Multiple keys in the same account share this balance; it is not a separate per-key balance. A procurement-order key returns that order's prepaid available, reserved, and settled amounts, with source: "market_order".

GET/v1/requests?page=1

Request Records

Returns paginated request records from the last 90 days for the current API key. The server fixes page size at 20 records, so clients cannot change it with limit. Public fields include request ID, model, status, timestamps, tokens, cost, API key name, and masked key. Prompt and output content are not returned.

GET/v1/usage

Usage Summary

Aggregates request count, success and failure count, total cost, input tokens, and output tokens for the current API key. The scope matches /v1/requests.

GET/v1/key

API Key Info

Returns cumulative and rolling daily, weekly, and monthly usage plus the current key limit and remaining amount.

terminal

Client Integration

Follow the guide for your CLI, SDK, or desktop client to configure its Base URL, API key, or launcher.

cURL

The fastest connectivity check.

cURL
curl https://api.wokey.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'
view_list

Models & Pricing

Model IDs and pricing come from the public model page and pricing catalog.

Model IDs

The request model must match the model ID shown on the Wokey model page.

Pricing catalog

Pricing follows the public model page and pricing catalog. Different models, cache paths, and upstream routes may bill differently.

Balance and records

After signing in, the API page shows balance, key cost, request records, and top-up records.

troubleshoot

Errors & Troubleshooting

Separate auth, balance, rate limit, model availability, and upstream timeout cases first.

401

invalid api key

The key is missing, mistyped, deleted, or Authorization / x-api-key headers conflict.

402

insufficient balance

The account balance is too low. Top up before sending more requests.

429

rate limited

Traffic is too frequent. Retry later or reduce concurrency.

502

upstream unavailable

The upstream model service is temporarily unavailable. Switch models or retry later.

504

upstream timeout

The upstream response timed out. Shorten context, reduce max_tokens, or retry.

529

upstream overloaded

The upstream model is temporarily overloaded and Wokey already retried on other routes (code upstream_unavailable). It is unrelated to your balance. Retry shortly or switch models.