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

modelRequired. See pricing for the list we actually run.
promptRequired.
nImages per call. Capped per model; the cap is enforced, not silently ignored.
sizeOptional. 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 / queuedAccepted upstream, not started.
running / processingIn progress. Poll every 3–5 seconds; faster gets you nothing.
succeededArtifacts available. Read data.artifacts.
failedTerminal. 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"}}
401Invalid or missing key.
403Key valid, model not enabled for your account.
402Balance exhausted.
503 model_not_foundNo healthy upstream for that model right now. Retry with backoff, or pick an equivalent model.
504Upstream 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.