Images & media

OneHop exposes image generation and editing on the same OpenAI-compatible base URL you already use for chat. Pass an image-capable model slug, and the request is billed per the real number of images returned.

Find image-capable models by filtering the catalog:

curl "https://api.onehop.ai/v1/models?capability=image_generation" \
  -H "Authorization: Bearer $ONEHOP_API_KEY"

Generate an image

curl https://api.onehop.ai/v1/images/generations \
  -H "Authorization: Bearer $ONEHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A paper map of the world folded into a single hop",
    "n": 1
  }'

Vertex / Gemini images

Gemini image models (such as Nano Banana) route through the Vertex-compatible base URL https://api.onehop.ai/vertex-ai. Output images are read from the provider response, so multi-image responses are billed accurately.

Long-running and async jobs

Image and video generation can take longer than a synchronous HTTP request should hold open. When enabled, the async jobs surface lets you submit work and poll for the result:

POST   /v1/jobs        # kind: "image_generation" | "video_generation"
GET    /v1/jobs/:id
GET    /v1/jobs
DELETE /v1/jobs/:id     # cancel a queued job

Async jobs still authenticate with your API key, hold wallet credit, and settle usage through the same billing path as synchronous requests — there is no separate billing channel. Job status moves through queued, running, completed, failed, cancelled, and expired. Pass X-Idempotency-Key so a retried submission returns the existing job instead of creating a duplicate.

See Video generation for the video-specific modes.