Documentation
One bearer token, OpenAI-shaped requests, task polling for anything that takes longer than a request should.
Authentication
Every request carries the key in an Authorization header.
Authorization: Bearer sk-your-key
Base URL: https://api.apicove.ai/v1. Keys are per-account; usage is metered in USD and deducted from your balance at the listed price. A request that never runs is never charged.
Image generation
Synchronous for most models, task-based for a few. Always check for task_id before reading url.
# curl
curl https://api.apicove.ai/v1/images/generations \
-H "Authorization: Bearer $APICOVE_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-nano-banana-2.1",
"prompt": "linen shirt on a wooden hanger, studio light, 1:1",
"n": 1
}'
# python (OpenAI SDK)
from openai import OpenAI
client = OpenAI(api_key="sk-...", base_url="https://api.apicove.ai/v1")
r = client.images.generate(model="gemini-nano-banana-2.1", prompt="linen shirt on a hanger", n=1)
print(r.data[0].url)
Request fields
| model | Required. See pricing for the list we actually run. |
| prompt | Required. |
| n | Images per call. Capped per model; the cap is enforced, not silently ignored. |
| size | Optional. Accepted forms differ by model family; omit it and the model's default applies. |
A few upstreams answer asynchronously even for images. The response then carries data[0].task_id instead of a URL — poll the task endpoint until it reaches a terminal state.
Video generation
Always asynchronous. Submit, then poll.
curl https://api.apicove.ai/v1/videos/generations \
-H "Authorization: Bearer $APICOVE_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0",
"prompt": "a linen shirt turning slowly on a mannequin, soft studio light",
"duration": 5
}'
# 202 + task handle
{"code":200,"data":[{"status":"submitted","task_id":"task_9pqV64qp..."}]}
Video is billed per second of generated output: a 5-second clip costs 5× the per-second price on the pricing table. Duration limits are per model.
Polling a task
curl https://api.apicove.ai/v1/tasks/task_9pqV64qp... \
-H "Authorization: Bearer $APICOVE_KEY"
Status lives at data.status. Terminal states are success and failure; failures explain themselves at data.error.message.
| submitted / queued | Accepted upstream, not started. |
| running / processing | In progress. Poll every 3–5 seconds; faster gets you nothing. |
| succeeded | Artifacts available. Read data.artifacts. |
| failed | Terminal. Balance for the attempt is returned. |
Downloading artifacts
Generated media is served from our own edge, not from a signed upstream link that expires in minutes.
GET /v1/tasks/{task_id}/artifacts/video/content
GET /v1/tasks/{task_id}/artifacts/image/content
Files stay available for 30 days counted from the first download, then a lifecycle rule removes them. After that the file is gone and cannot be restored — mirror anything you need to keep.
Errors
Always the same envelope, so you can branch on code alone.
{"error":{"code":"model_not_found","message":"No available channel for model ...","type":"new_api_error"}}
| 401 | Invalid or missing key. |
| 403 | Key valid, model not enabled for your account. |
| 402 | Balance exhausted. |
| 503 model_not_found | No healthy upstream for that model right now. Retry with backoff, or pick an equivalent model. |
| 504 | Upstream timeout. The task may still finish — poll the task id if you have one. |
Machine-readable index
/llms.txt lists every endpoint and model with its unit price, in the format LLM coding agents read directly. /pricing.json is the same data as JSON, if your own tooling wants to diff it.