# API.market media router

> One API for the image, video, audio, understanding and 3D models listed on
> API.market. Every job runs through the API.market gateway on the caller's
> own key and is billed there by the listing's rule.

Base URL: https://router.api.market
Auth: `Authorization: Bearer <API.market key>` on every create and on `GET /v1/jobs/{id}`.
Full reference: [OpenAPI 3.1](https://router.api.market/openapi.json)

## Find a model

- `GET /v1/models` (no key): every model a job can run on now, across all
  outputs, with live pricing, a typical cost and 30-day stats
  (`runs_30d`, `success_rate`, `p50_seconds`). Query: `task`, `output`
  (image, video, audio, text, 3d), `priority`, `max_price` (dollars), `limit`
  (default 20).
- `GET /v1/images/models`, `/v1/videos/models`, `/v1/audio/models`,
  `/v1/understand/models`, `/v1/3d/models`: one output's models with their
  manifests (input roles, parameters).

## Run a job

POST the same body to the endpoint for the output you want:
`/v1/images`, `/v1/videos`, `/v1/audio`, `/v1/understand` (text or JSON
answers) or `/v1/3d`.

```json
{"model": "bytedance/seedream-4.5", "prompt": "a red shoe on white",
 "input_references": [{"type": "image_url", "image_url": {"url": "https://..."}, "role": "reference"}],
 "parameters": {}, "priority": "balanced"}
```

- `model: "auto"` with a `use_case` ("product shots for a shoe store") lets
  API.market pick the model; the answer carries `routing.reason` ("auto: ...")
  and `resolved_request`.
- `dry_run: true` returns the resolved request and its estimated cost with no
  charge and no job.
- `priority`: `cost`, `speed`, `quality` (your order of `models`) or
  `balanced` (default). `provider.sort` is an alias.
- `models`: fallback models doing the same task, tried after a failure that
  was not billed.
- `Prefer: wait=N` (at most 45) waits for the result; images and
  understanding wait 30 s by default, other outputs answer 202 at once. A
  call never takes more than 45 s.
- `Idempotency-Key`: a repeat within 24 hours returns the same job.

A 200 is the finished job (image jobs in the OpenAI images shape). A 202 has
a `polling_url`; `GET /v1/jobs/{id}` until `status` is `succeeded` or
`failed`. Output links last 24 hours.

## Money

The wallet holds the most a job can cost before it runs (402
`insufficient_balance` when it cannot pay for the model asked for; a wallet
that covers it but not a dearer fallback runs without that fallback). The gateway bills what ran;
`cost.amount` is the router's estimate of that charge, and the API.market
usage log has the billed amount. A job a listing may have started is never
run again on another listing.

## Limits

- 50 jobs queued or running per account (429 `too_many_active_jobs`).
- 16 job requests starting at once per account, `auto` picks included
  (429 `too_many_parallel_requests`).
- A job runs for at most 10 minutes (images, text), 15 (audio, 3D) or 30
  (video).
- Bodies up to 16 MB; send inputs as HTTPS URLs where you can (503 `busy`
  when too many large bodies arrive at once, or an account sends more than
  two over 1 MB at a time). Prompts up to 32,000
  characters.

## Errors

RFC 9457 problems (`application/problem+json`) with a stable `code`,
`retryable`, and `param` where one field is at fault. The codes are listed in
the OpenAPI document under `Problem.code`.