API Reference
Overview
Endpoints and conventions for the asynchronous image API.
TokLab serves image, video, audio and text models through one API and one API key. Image, video and audio models run as asynchronous tasks: you submit a request, receive a task ID and poll for the result. Text models answer directly, in the request format of the model's vendor.
Base URL
https://api.toklab.aiUse HTTPS and send JSON request bodies. The audio endpoints take a multipart/form-data upload instead.
Authentication
Send your key as a Bearer token on every request, including task queries:
Authorization: Bearer YOUR_API_KEYThe Anthropic Messages endpoint also accepts the key in x-api-key, together with the anthropic-version header. See Authentication.
Media task endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/images/generations | Submit an image generation or editing task: GPT Image, Nano Banana and Midjourney. |
| POST | /v1/videos/generations | Submit a video task: Seedance 2.5 and 2.0 (ModelArk request body), Veo 3.1, Kling 3.0, MiniMax H3 and SD Video. |
| POST | /v1/audio/transcriptions | Submit an audio file for transcription with Whisper-1. |
| POST | /v1/audio/translations | Submit an audio file for translation into English with Whisper-1. |
| GET | /v1/tasks/{id} | Read the state and result of an image, video or audio task. |
Reference images, videos and audio are passed as URLs in the request body. An image request becomes an edit when it includes input images. Each model's reference lists its parameters.
Text endpoints
| Method | Path | Request format |
|---|---|---|
| POST | /v1/chat/completions | OpenAI Chat Completions |
| POST | /v1/responses | OpenAI Responses |
| POST | /v1/messages | Anthropic Messages |
| POST | /v1beta/models/{model}:generateContent | Google Gemini |
| POST | /v1beta/models/{model}:streamGenerateContent | Google Gemini, streamed |
| GET | /v1/models | List the available models |
Not every text model supports every format. The model's API reference names the formats it accepts; for example, Claude Opus 5.5 accepts Chat Completions, Responses and Messages, while the Gemini text models use the /v1beta paths.
Request lifecycle
Media tasks
- Submit the request. The response is a task, not the finished file: store its
id. - Poll the task until it reaches a final state. Tasks on
/v1/tasks/{id}reportprocessing, thencompletedorfailed. - Read the result. Images are in
output.data[].url, videos inoutput.video_url, and Whisper output inoutput.url. Every result link points to TokLab's storage.
On failure, inspect error.code and error.message. Failed tasks are not charged. There is no completion webhook; poll the task instead, as described in Webhooks.
Text requests
A text request returns the model's answer in the same response, in the vendor's official response shape. Set stream to true, or use :streamGenerateContent for Gemini, to receive server-sent events. Text models are billed per token.