# BazaarLink Documented Endpoint Reference > Registry-backed English Markdown for all 40 public endpoints with dedicated BazaarLink reference pages. Internal, legacy, alias, and documentation-hold routes are intentionally not promoted as public API. Canonical: https://bazaarlink.ai/docs/api-reference OpenAPI JSON: https://bazaarlink.ai/docs/openapi.json OpenAPI YAML: https://bazaarlink.ai/docs/openapi.yaml Registry entries: 40 # Chat ## POST /api/v1/chat/completions **Create a chat** Requests a model response for the given chat conversation. Supports both streaming and non-streaming modes, with one OpenAI-compatible request/response shape across every model and provider. Authentication: Bearer API key required ### Request body | Name | Type | Required | Description | |---|---|---:|---| | `model` | `string` | yes | The model to use, provider-qualified, e.g. "openai/gpt-4.1". Short ids from common model families (e.g. "gpt-4o") are automatically resolved to the full canonical id ("openai/gpt-4o"); values already in canonical form pass through unchanged. An unrecognized short id is not force-rewritten — model resolution surfaces a clear model-not-found error instead. minLength: 1 Example: "openai/gpt-4.1" | | `messages` | `Message[]` | yes | Array of conversation messages, at least one. Each has a role (system/user/assistant/tool) and content. minLength: 1 | | `models` | `string[]` | no | Fallback model list — tried in order, only used once the primary model's own candidate group is exhausted. | | `stream` | `boolean` | no | true streams the response as SSE; omitted or false returns a single JSON response. | | `temperature` | `number` | no | Sampling temperature — higher is more random, lower is more deterministic. 0–2 | | `max_tokens` | `integer` | no | Maximum number of tokens the response may generate. | | `max_completion_tokens` | `integer` | no | Alias of max_tokens with identical semantics. | | `top_p` | `number` | no | Nucleus sampling threshold. 0–1 | | `top_k` | `integer` | no | Limits sampling to the K highest-probability tokens. | | `frequency_penalty` | `number` | no | Penalizes tokens based on how often they've already appeared. -2.0–2.0 | | `presence_penalty` | `number` | no | Penalizes tokens based on whether they've appeared at all, regardless of count. -2.0–2.0 | | `repetition_penalty` | `number` | no | Repetition penalty coefficient — a separate mechanism from frequency/presence penalty. | | `min_p` | `number` | no | Minimum probability threshold relative to the most likely token. 0–1 | | `top_a` | `number` | no | Another dynamic-cutoff sampling mechanism, scaling the threshold by the square of the top probability. | | `seed` | `integer` | no | Deterministic sampling seed; not all providers guarantee reproducibility. | | `n` | `integer` | no | Number of completions to generate. | | `stop` | `string | string[]` | no | Sequences where generation stops, up to 4. | | `tools` | `Tool[]` | no | List of tool/function definitions the model may call. | | `tool_choice` | `string | object` | no | Controls whether/how the model is forced to call a tool. | | `parallel_tool_calls` | `boolean` | no | Whether to allow parallel tool calls when tools are provided. Default true. OpenAI-family models only — silently stripped when the target model isn't OpenAI's own, not an error. | | `response_format` | `object` | no | Constrains the output format, e.g. {type:"json_object"} or {type:"json_schema"} with a JSON Schema. | | `logit_bias` | `object` | no | Maps token IDs to bias values [-100, 100] added before sampling. OpenAI-family models only — silently stripped when the target model isn't OpenAI's own, not an error. | | `logprobs` | `boolean` | no | Return log probabilities of each output token. OpenAI-family models only — silently stripped when the target model isn't OpenAI's own, not an error. | | `top_logprobs` | `integer` | no | Number of most-likely tokens to return per position (requires logprobs: true). OpenAI-family models only — silently stripped when the target model isn't OpenAI's own, not an error. 0–20 | | `user` | `string` | no | End-user identifier for monitoring and abuse detection. Has no effect on billing. OpenAI-family models only — silently stripped when the target model isn't OpenAI's own, not an error. | | `reasoning` | `object` | no | Reasoning-model thinking control object (e.g. {effort, max_tokens}). | | `reasoning_effort` | `string` | no | Flat shorthand for reasoning.effort. Values: low, medium, high | | `image_config` | `object` | no | Image generation/edit options (used when modalities includes image). | | `modalities` | `string[]` | no | Requested output modalities. Including image routes through the image-generation dispatch path. Values: text, image | | `plugins` | `object[]` | no | Array of plugins (e.g. {id:"web"} to enable web search). Supported only on some model routes, no effect elsewhere; the :online model variant auto-injects {id:"web"}, likewise only on supporting routes. | ### cURL ```bash curl https://bazaarlink.ai/api/v1/chat/completions \ -H "Authorization: Bearer $BAZAARLINK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-4.1", "messages": [{"role": "user", "content": "Explain quantum computing in one paragraph."}] }' ``` ### Response 200 Success. BazaarLink normalizes exactly two fields — model, and the removal of a provider field — and forwards the rest of the upstream response as-is, including fields like native_finish_reason, system_fingerprint, and reasoning that are only present when that specific provider populates them. usage.cost is the exception — always BazaarLink's own settled amount, not a value relayed from upstream. ```json { "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1740000000, "model": "openai/gpt-4o", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Quantum computing leverages quantum mechanics..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 28, "completion_tokens": 74, "total_tokens": 102, "cost": 0.000648 } } ``` ### Response 400 Invalid request. Common causes: malformed body, missing model/messages, or unsupported_modality — the messages include image input but every route for this model explicitly lacks image support (this check exists only on this endpoint; when the catalog has no modality data the request is passed through for the upstream to judge, so not every text-only model is guaranteed to return 400). ```json { "error": { "message": "Model 'deepseek/deepseek-v4-flash' does not support image input.", "type": "invalid_request_error", "code": "unsupported_modality", "param": "messages" } } ``` ### Response 401 Missing Authorization header, or the API key is invalid or disabled. ```json { "error": { "message": "Invalid API key", "type": "invalid_request_error", "code": 401 } } ``` ### Response 402 Insufficient credits, or your weekly/monthly budget cap has been reached. ```json { "error": { "message": "Insufficient credits", "type": "invalid_request_error", "code": 402 } } ``` ### Response 429 Rate limit exceeded (RPM depends on your account tier), or an account-level spend brake has tripped. Retry later. ```json { "error": { "message": "Rate limit exceeded", "type": "invalid_request_error", "code": 429 } } ``` ### Response 503 Service temporarily unavailable — all upstream providers are circuit-broken, the global spend limit tripped, or the service is draining for restart. Retry later. ```json { "error": { "message": "Service temporarily unavailable — global spend limit reached. Try again shortly.", "type": "invalid_request_error", "code": 503 } } ``` ### Response 410 The model has been retired from the catalog — switch to a newer model ID. ```json { "error": { "message": "Model openai/gpt-3.5-turbo has been retired", "type": "model_not_available", "code": "model_retired" } } ``` --- # Messages (Anthropic) ## POST /api/v1/messages **Create a message** Requests a model response using Anthropic's native /v1/messages shape; BazaarLink routes it to any supported model, not just Anthropic's own. Point the official Anthropic SDK's base_url at BazaarLink and existing code works unchanged. Accepts either Authorization: Bearer or the Anthropic SDK's conventional x-api-key header. If the resolved model isn't native Anthropic, BazaarLink transparently translates the request/response, preserving tool_use blocks and stop_reason semantics where possible. Authentication: Bearer API key required ### Request body | Name | Type | Required | Description | |---|---|---:|---| | `model` | `string` | yes | The model to use, provider-qualified, e.g. "anthropic/claude-sonnet-4.6". minLength: 1 Example: "anthropic/claude-sonnet-4.6" | | `messages` | `Message[]` | yes | Array of conversation messages, at least one. Each has a role (user/assistant) and content (a string, or an array of content blocks such as text/image/tool_use/tool_result). minLength: 1 | | `max_tokens` | `integer` | yes | Maximum number of tokens the response may generate. Unlike the OpenAI-compatible endpoints, this field is required in the Anthropic shape. positive integer Example: 1024 | | `system` | `string | ContentBlock[]` | no | System prompt — a separate top-level field, not a message inside the messages array (one of the main shape differences from the OpenAI format). | | `stream` | `boolean` | no | true streams the response as SSE (message_start / content_block_delta / message_delta / message_stop events); omitted or false returns a single JSON response. | | `temperature` | `number` | no | Sampling temperature — higher is more random, lower is more deterministic. Not validated by BazaarLink — forwarded as-is to the upstream. If the resolved model isn't native Anthropic, how this field is handled depends on BazaarLink's translation layer. 0–1 | | `top_p` | `number` | no | Nucleus sampling threshold. Not validated by BazaarLink — forwarded as-is to the upstream. If the resolved model isn't native Anthropic, how this field is handled depends on BazaarLink's translation layer. 0–1 | | `top_k` | `integer` | no | Limits sampling to the K highest-probability tokens. Not validated by BazaarLink — forwarded as-is to the upstream. If the resolved model isn't native Anthropic, how this field is handled depends on BazaarLink's translation layer. | | `stop_sequences` | `string[]` | no | Array of strings where generation stops. Not validated by BazaarLink — forwarded as-is to the upstream. If the resolved model isn't native Anthropic, how this field is handled depends on BazaarLink's translation layer. | | `tools` | `Tool[]` | no | List of tool definitions the model may call, Anthropic-shaped (name, description, input_schema). Not validated by BazaarLink — forwarded as-is to the upstream. If the resolved model isn't native Anthropic, how this field is handled depends on BazaarLink's translation layer. | | `tool_choice` | `object` | no | Controls whether/how the model is forced to call a tool, e.g. {type:"auto"}, {type:"any"}, {type:"tool", name:"..."}. Not validated by BazaarLink — forwarded as-is to the upstream. If the resolved model isn't native Anthropic, how this field is handled depends on BazaarLink's translation layer. | | `thinking` | `object` | no | Extended-thinking control object, e.g. {type:"enabled", budget_tokens:2048}. Only meaningful on reasoning models. Not validated by BazaarLink — forwarded as-is to the upstream. If the resolved model isn't native Anthropic, how this field is handled depends on BazaarLink's translation layer. | | `metadata` | `object` | no | Request metadata, e.g. {user_id:"..."}. Used for monitoring and abuse detection; has no effect on billing. Not validated by BazaarLink — forwarded as-is to the upstream. If the resolved model isn't native Anthropic, how this field is handled depends on BazaarLink's translation layer. | ### cURL ```bash curl https://bazaarlink.ai/api/v1/messages \ -H "Authorization: Bearer $BAZAARLINK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "anthropic/claude-sonnet-4.6", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}] }' ``` ### Response 200 Success. By default (or stream: false) returns the Anthropic-native Message object below; with stream: true, returns an SSE event stream instead (message_start / content_block_delta / message_delta / message_stop — see the deep guide for the protocol). model always echoes the name you requested (never the actually-resolved upstream model). usage keeps the native Anthropic fields (input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens) plus cost/bz_cost — BazaarLink's own settled amount, never a value relayed from upstream. ```json { "id": "msg_01XFDUDYJgAACzvnptvVoYEL", "type": "message", "role": "assistant", "model": "anthropic/claude-sonnet-4.6", "content": [ { "type": "text", "text": "Hello! How can I help you today?" } ], "stop_reason": "end_turn", "stop_sequence": null, "usage": { "input_tokens": 10, "output_tokens": 12, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "cost": 0.000186, "bz_cost": 0.000186 } } ``` ### Response 400 Invalid request — malformed JSON, missing required fields, or failed validation. ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "'max_tokens' is required and must be a positive integer." } } ``` ### Response 401 Missing Authorization header, or the API key is invalid or disabled. ```json { "type": "error", "error": { "type": "authentication_error", "message": "Invalid API key" } } ``` ### Response 402 Insufficient credits, or your weekly/monthly budget cap has been reached. ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "Insufficient credits" } } ``` ### Response 410 The model has been retired from the catalog — switch to a newer model ID. ```json { "error": { "message": "Model anthropic/claude-2 has been retired", "type": "model_not_available", "code": "model_retired", "param": "model" } } ``` ### Response 413 Request body too large (10 MB limit). ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "Request body too large (max 10 MB)." } } ``` ### Response 429 Rate limit exceeded (RPM depends on your account tier), or an account-level spend brake has tripped. Retry later. ```json { "type": "error", "error": { "type": "rate_limit_error", "message": "Rate limit exceeded (free tier)." } } ``` ### Response 503 Service temporarily unavailable — all upstream providers are circuit-broken, the global spend limit tripped, or the service is draining for restart. Retry later. ```json { "type": "error", "error": { "type": "overloaded_error", "message": "Service temporarily unavailable — global spend limit reached. Try again shortly." } } ``` --- # Responses API ## POST /api/v1/responses **Create a response** Requests a model response using the OpenAI Responses API request shape (input/instructions); internally converted to Chat Completions format and routed to any supported model — this is a translation layer, not a separate inference path. This is a stateless endpoint: passing store: true or a non-null previous_response_id returns 400 (see the 400 entry below for its distinct error shape) — every call must carry the full conversation in input. When streaming, reasoning is surfaced via response.reasoning_text.delta events and a type:"reasoning" output item. Authentication: Bearer API key required ### Request body | Name | Type | Required | Description | |---|---|---:|---| | `model` | `string` | yes | The model to use, provider-qualified, e.g. "openai/gpt-5.2". minLength: 1 Example: "openai/gpt-5.2" | | `input` | `string | InputItem[]` | yes | Conversation input — either a single string, or a structured array of items (message/function_call/function_call_output). Messages may use plain text or a content-block array including input_image. | | `instructions` | `string` | no | System-level instructions, inserted as the first system message at the front of the converted messages array. | | `stream` | `boolean` | no | true streams the response as Responses-API SSE events (response.created, response.output_item.added, response.output_text.delta, response.reasoning_text.delta, response.completed, and others); omitted or false returns a single JSON response. | | `max_output_tokens` | `integer` | no | Maximum number of tokens the response may generate (converted to the upstream Chat Completions max_tokens). | | `tools` | `Tool[]` | no | List of tool/function definitions the model may call. Accepts the Responses-spec flat shape {type:"function", name, description, parameters} (recommended), and also the Chat Completions nested shape {type:"function", function:{...}} (accepted for back-compat, passed through as-is). The response object's tools field echoes whatever was actually sent here. | | `tool_choice` | `string | object` | no | Controls whether/how the model is forced to call a tool, e.g. {type:"function", name:"..."} (flat shape, recommended, auto-converted for upstream) or "auto". The response object's tool_choice field echoes whatever was sent here, defaulting to "auto" when omitted. | | `parallel_tool_calls` | `boolean` | no | Whether to allow parallel tool calls when tools are provided. Defaults to true when omitted; the response object's parallel_tool_calls field echoes whatever was sent here. | | `plugins` | `object[]` | no | Array of plugins (e.g. {id:"web"} to enable web search). Supported only on some model routes, no effect elsewhere; the :online model variant auto-injects {id:"web"} only when you didn't send any plugins, likewise only on supporting routes. | | `store` | `boolean` | no | ⚠️ This endpoint is stateless — passing true returns 400 immediately, it is never accepted or silently ignored. Omitting it or passing false is the only valid usage. | | `previous_response_id` | `string` | no | ⚠️ This endpoint is stateless — passing any non-null value returns 400 immediately, it is never accepted or silently ignored. To continue a conversation, send the full history in the input array instead. | | `models` | `string[]` | no | Fallback model list — tried in order, only used once the primary model's own candidate group is exhausted. | | `reasoning` | `object` | no | Reasoning-model thinking control object (e.g. {effort, max_tokens}), forwarded as-is upstream — no defaults are injected. | | `reasoning_effort` | `string` | no | Flat shorthand for reasoning.effort. Values: low, medium, high | | `thinking` | `object` | no | Claude extended-thinking's additive token budget (e.g. {type:"enabled", budget_tokens:2048}), on top of max_output_tokens — forwarded as-is, no defaults injected. | | `enable_thinking` | `boolean` | no | Thinking on/off toggle for Qwen3/GLM-family models, forwarded as-is. | ### cURL ```bash curl https://bazaarlink.ai/api/v1/responses \ -H "Authorization: Bearer $BAZAARLINK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-5.2", "input": "What is the capital of France?" }' ``` ### Response 200 Success. By default (or stream: false) returns the Response object below; with stream: true, returns the Responses API's SSE event stream instead. model always echoes the name you requested. output[] is composed of whatever was actually produced: a type:"reasoning" item first when reasoning content was present, followed by a type:"message" text item (its content's annotations array may carry citation sources, e.g. url_citation from a web search hit), or a type:"function_call" item. usage is converted from the underlying Chat Completions usage (input_tokens/output_tokens/total_tokens/cost), with an additional output_tokens_details.reasoning_tokens when reasoning tokens were used. tool_choice/tools/parallel_tool_calls echo whatever you actually sent in the request. ```json { "id": "resp_6f2a1c9d8e7b4a3f9c1d2e3f", "object": "response", "created_at": 1753500000, "completed_at": 1753500002, "status": "completed", "model": "openai/gpt-5.2", "output": [ { "type": "reasoning", "id": "rs_1a2b3c4d5e6f7a8b9c0d1e2f", "status": "completed", "summary": [], "content": [ { "type": "reasoning_text", "text": "The user is asking a simple geography fact..." } ] }, { "type": "message", "id": "msg_9f8e7d6c5b4a3f2e1d0c9b8a", "role": "assistant", "status": "completed", "content": [ { "type": "output_text", "text": "The capital of France is Paris.", "annotations": [] } ] } ], "usage": { "input_tokens": 14, "output_tokens": 32, "total_tokens": 46, "cost": 0.00021, "output_tokens_details": { "reasoning_tokens": 18 } }, "error": null, "incomplete_details": null, "tool_choice": "auto", "tools": [], "truncation": "auto", "parallel_tool_calls": true, "metadata": {}, "store": false } ``` ### Response 400 Invalid request. Most causes (malformed JSON, missing required fields, input converted to zero messages, context exceeding the model's limit) use the standard {error:{message,type,code}} shape. ⚠️ One exception: passing store: true or a non-null previous_response_id uses {error:{code:"invalid_prompt",message,type},metadata:null} instead — a STRING code, not a number, plus an extra top-level metadata field, as shown in the example below. ```json { "error": { "code": "invalid_prompt", "message": "This API is stateless: 'previous_response_id' is not supported. Pass the full conversation history in the 'input' array instead.", "type": "invalid_request_error" }, "metadata": null } ``` ### Response 401 Missing Authorization header, or the API key is invalid or disabled. ```json { "error": { "message": "Invalid API key", "type": "invalid_request_error", "code": 401 } } ``` ### Response 402 Insufficient credits, or your weekly/monthly budget cap has been reached. ```json { "error": { "message": "Insufficient credits", "type": "invalid_request_error", "code": 402 } } ``` ### Response 410 The model has been retired from the catalog — switch to a newer model ID. ```json { "error": { "message": "Model openai/gpt-4-vision has been retired", "type": "model_not_available", "code": "model_retired", "param": "model" } } ``` ### Response 429 Rate limit exceeded (RPM depends on your account tier), or an account-level spend brake has tripped. Retry later. ```json { "error": { "message": "Rate limit exceeded (free tier). Please slow down.", "type": "invalid_request_error", "code": 429 } } ``` ### Response 503 Service temporarily unavailable — all upstream providers are circuit-broken, the global spend limit tripped, or this tier was disabled by an admin. Retry later. ```json { "error": { "message": "Service temporarily unavailable. Please retry shortly.", "type": "api_error", "code": 502 } } ``` --- # Images ## POST /api/v1/images/generations **Generate an image** Generates an image from a text prompt. Returns OpenAI-compatible sync JSON by default (works with client.images.generate()); pass stream: true to get an SSE event stream instead. Image-to-image is supported via inputImages / input_references. Authentication: Bearer API key required ### Request body | Name | Type | Required | Description | |---|---|---:|---| | `model` | `string` | yes | The image generation model to use, provider-qualified, e.g. "openai/gpt-image-2". minLength: 1 Example: "openai/gpt-image-2" | | `prompt` | `string` | yes | Text description of the desired image. minLength: 1 Example: "a red cat on a sofa" | | `n` | `integer` | no | Number of images to generate, 1–10. 1–10 Example: 1 | | `size` | `string` | no | Image size — explicit pixels ("2048x2048") or a tier ("2K", "4K"). Forwarded to the provider as-is; supported sizes vary by model. Example: "1024x1024" | | `stream` | `boolean` | no | Selects the response shape: omitted or false = OpenAI-compatible sync JSON (the default), true = SSE event stream. | | `input_references` | `string[]` | no | Source images for image-to-image (data: or https: URLs), up to 8. Alias of inputImages (industry-conventional field name); both pass content moderation first. Returns 400 — not a warning — when the model's route does not support i2i. ≤ 8 images | | `aspect_ratio` | `enum` | no | Aspect ratio of the generated image. Natively supported on some model routes — check supported_parameters in the GET /api/v1/images/models response for each model; unsupported routes ignore the field and note it in the response's warnings[] (the request still succeeds). Values: 1:1, 1:2, 1:4, 1:8, 2:1, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 9:19.5, 19.5:9, 9:20, 20:9, 9:21, 21:9, auto Example: "16:9" | | `resolution` | `enum` | no | Resolution tier; concrete pixels are derived per provider. Natively supported on some model routes — check supported_parameters in the GET /api/v1/images/models response for each model; unsupported routes ignore the field and note it in the response's warnings[] (the request still succeeds). Values: 512, 1K, 2K, 4K Example: "2K" | | `quality` | `enum` | no | Rendering quality. Natively supported on some model routes — check supported_parameters in the GET /api/v1/images/models response for each model; unsupported routes ignore the field and note it in the response's warnings[] (the request still succeeds). Values: auto, low, medium, high | | `background` | `enum` | no | Background treatment; transparent requires an alpha-capable output_format (png/webp). Natively supported on some model routes — check supported_parameters in the GET /api/v1/images/models response for each model; unsupported routes ignore the field and note it in the response's warnings[] (the request still succeeds). Values: auto, transparent, opaque | | `output_format` | `enum` | no | Encoding of the returned image bytes. Natively supported on some model routes — check supported_parameters in the GET /api/v1/images/models response for each model; unsupported routes ignore the field and note it in the response's warnings[] (the request still succeeds). Values: png, jpeg, webp, svg Example: "png" | | `output_compression` | `integer` | no | Compression level (0–100) for webp/jpeg output; ignored for png. Natively supported on some model routes — check supported_parameters in the GET /api/v1/images/models response for each model; unsupported routes ignore the field and note it in the response's warnings[] (the request still succeeds). 0–100 Example: 100 | | `seed` | `integer` | no | Deterministic sampling seed; identical seed + parameters should reproduce the result, though not all providers guarantee it. Natively supported on some model routes — check supported_parameters in the GET /api/v1/images/models response for each model; unsupported routes ignore the field and note it in the response's warnings[] (the request still succeeds). | ### cURL ```bash curl https://bazaarlink.ai/api/v1/images/generations \ -H "Authorization: Bearer $BAZAARLINK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-image-2", "prompt": "a red cat on a sofa", "size": "1024x1024" }' ``` ### Response 200 Success. By default (or stream: false) returns the sync JSON below; with stream: true, returns an SSE event stream (see the deep guide for the event protocol). Parameters ignored by the route appear in top-level warnings[] (informational only). ```json { "created": 1753500000, "data": [ { "url": "https://bazaarlink.ai/api/v1/images/proxy/eyJhbGciOi..." } ], "warnings": [ { "param": "aspect_ratio", "action": "dropped", "reason": "'aspect_ratio' is not yet mapped for this model's upstream and was ignored; the image was still generated using the model's default." } ] } ``` ### Response 400 Invalid request — malformed JSON, missing required fields, or failed validation. ```json { "error": { "message": "'model' is required.", "type": "invalid_request_error", "code": 400 } } ``` ### Response 401 Missing Authorization header, or the API key is invalid or disabled. ```json { "error": { "message": "Invalid API key", "type": "invalid_request_error", "code": 401 } } ``` ### Response 402 Insufficient credits, or your weekly/monthly budget cap has been reached. ```json { "error": { "message": "Insufficient credits", "type": "invalid_request_error", "code": 402 } } ``` ### Response 429 Rate limit exceeded (RPM depends on your account tier), or an account-level spend brake has tripped. Retry later. ```json { "error": { "message": "Rate limit exceeded", "type": "invalid_request_error", "code": 429 } } ``` ### Response 503 Service temporarily unavailable — all upstream providers are circuit-broken, the global spend limit tripped, or the service is draining for restart. Retry later. ```json { "error": { "message": "Service temporarily unavailable — global spend limit reached. Try again shortly.", "type": "invalid_request_error", "code": 503 } } ``` ### Response 410 The model has been retired from the catalog — switch to a newer model ID. ```json { "error": { "message": "Model openai/dall-e-2 has been retired", "type": "model_not_available", "code": "model_retired" } } ``` ### Response 413 Request body too large (10 MB limit). ```json { "error": { "message": "Request body too large (max 10 MB).", "type": "invalid_request_error", "code": 413 } } ``` --- ## POST /api/v1/images/edits **Edit an image** Uploads source images as multipart/form-data and edits them with a text prompt — compatible with OpenAI client.images.edit(). Reuses the image-to-image pipeline internally; the response is always sync JSON. mask is not supported yet, and response_format only supports URLs (b64_json is rejected). Authentication: Bearer API key required ### Request body | Name | Type | Required | Description | |---|---|---:|---| | `image` | `file` | yes | Source image file(s) to edit. Repeat the image field (or use image[]) for multiple files — up to 8, 10 MB each, MIME must be image/*. ≤ 8 files, ≤ 10 MB each, image/* | | `prompt` | `string` | yes | Text description of the edit to apply. minLength: 1 Example: "change the background to a night city" | | `model` | `string` | no | The image edit model. When omitted, the server default applies (currently gpt-5.4-image-2). Example: "openai/gpt-5.4-image-2" | | `n` | `integer` | no | Number of results to generate, 1–10. 1–10 Example: 1 | | `size` | `string` | no | Output size, must be a "x" pixel string (e.g. 1024x1024); values in any other format are silently ignored. format: x Example: "1024x1024" | ### cURL ```bash curl https://bazaarlink.ai/api/v1/images/edits \ -H "Authorization: Bearer $BAZAARLINK_API_KEY" \ -F model="openai/gpt-5.4-image-2" \ -F image=@cat.png \ -F prompt="change the background to a night city" ``` ### Response 200 Success. Always returns sync JSON (the SSE stream is drained internally) — compatible with client.images.edit(). ```json { "created": 1753500000, "data": [ { "url": "https://bazaarlink.ai/api/v1/images/proxy/eyJhbGciOi..." } ] } ``` ### Response 401 Missing Authorization header, or the API key is invalid or disabled. ```json { "error": { "message": "Invalid API key", "type": "invalid_request_error", "code": 401 } } ``` ### Response 402 Insufficient credits, or your weekly/monthly budget cap has been reached. ```json { "error": { "message": "Insufficient credits", "type": "invalid_request_error", "code": 402 } } ``` ### Response 429 Rate limit exceeded (RPM depends on your account tier), or an account-level spend brake has tripped. Retry later. ```json { "error": { "message": "Rate limit exceeded", "type": "invalid_request_error", "code": 429 } } ``` ### Response 503 Service temporarily unavailable — all upstream providers are circuit-broken, the global spend limit tripped, or the service is draining for restart. Retry later. ```json { "error": { "message": "Service temporarily unavailable — global spend limit reached. Try again shortly.", "type": "invalid_request_error", "code": 503 } } ``` ### Response 400 Invalid request — malformed JSON, missing required fields, or failed validation. ```json { "error": { "message": "mask is not supported yet", "type": "invalid_request_error", "code": "mask_not_supported" } } ``` ### Response 410 The model has been retired from the catalog — switch to a newer model ID. ```json { "error": { "message": "Model openai/dall-e-2 has been retired", "type": "model_not_available", "code": "model_retired" } } ``` ### Response 413 Request body too large (10 MB limit). ```json { "error": { "message": "Request body too large (max 10 MB).", "type": "invalid_request_error", "code": 413 } } ``` --- ## GET /api/v1/images/proxy/:token **Fetch a cached image** Returns the raw bytes of a generated image. The image-cached events and data[].url values in generation responses point here; the token itself is the access credential (no API key needed) and expires after 1 hour, after which the endpoint returns 404. Authentication: Public ### Path parameters | Name | Type | Required | Description | |---|---|---:|---| | `token` | `string` | yes | The image token issued in the generation response. Only UUID v4 is accepted; anything else returns 404. UUID v4 | ### cURL ```bash curl -o result.png \ https://bazaarlink.ai/api/v1/images/proxy/9f1c2d3e-4a5b-4c6d-8e7f-0a1b2c3d4e5f ``` ### Response 200 Success. Returns the raw image bytes (not JSON) with the image's MIME as Content-Type (SVG is neutralized to application/octet-stream to prevent same-origin script execution) and a 1-hour immutable cache header. ```text HTTP/1.1 200 OK Content-Type: image/png Content-Length: 428381 Cache-Control: public, max-age=3600, immutable X-Content-Type-Options: nosniff Content-Security-Policy: sandbox ``` ### Response 404 The token is not a UUID v4, or the image has expired (1-hour TTL) or never existed. The response body is plain text, not JSON. ```text Image expired or not found ``` ### Response 503 The cache storage is temporarily unavailable. The response body is plain text, not JSON. ```text Storage unavailable ``` --- ## GET /api/v1/images/models **List image generation models** Lists every available image generation model, each with supported_parameters — the authoritative list of what that model's route actually accepts (e.g. whether aspect_ratio is honored natively, whether input_references enables image-to-image). No auth required; with an organization API key, the response is filtered by the org's model allowlist. Authentication: Public ### cURL ```bash curl https://bazaarlink.ai/api/v1/images/models ``` ### Response 200 Success. Returns the model list; cached for 5 minutes (private, uncached with an organization key). supported_parameters is the authoritative per-route support table. ```json { "object": "list", "data": [ { "id": "openai/gpt-image-2", "object": "model", "created": 1753500000, "owned_by": "openai", "name": "GPT Image 2", "description": "…", "pricing": { "prompt": "0.000005", "completion": "0.00004", "image": "0.04" }, "architecture": { "modality": "text+image->image", "input_modalities": [ "text", "image" ], "output_modalities": [ "image" ] }, "supported_parameters": [ "model", "prompt", "n", "size", "stream", "aspect_ratio", "resolution", "quality", "background", "output_format", "output_compression", "seed", "input_references" ] } ] } ``` ### Response 500 The server temporarily failed to fetch the model list. Retry later. ```json { "error": { "message": "Failed to fetch image models", "type": "server_error", "code": 500 } } ``` --- # Embeddings ## POST /api/v1/embeddings **Create embeddings** Converts text (or, for models that support it, multimodal content) into vector embeddings. Request and response shapes match OpenAI's embeddings API, so it works directly with client.embeddings.create(). input accepts a single string or an array of strings. Authentication: Bearer API key required ### Request body | Name | Type | Required | Description | |---|---|---:|---| | `model` | `string` | yes | The embeddings model to use, provider-qualified, e.g. "openai/text-embedding-3-small". minLength: 1 Example: "openai/text-embedding-3-small" | | `input` | `string | string[]` | yes | The text to embed. Accepts a single string, or an array of strings to embed multiple inputs in one request. Some models additionally accept structured multimodal content items, forwarded to the upstream as-is; actual support depends on the model. Example: "The quick brown fox" | | `encoding_format` | `string` | no | Encoding format, forwarded to the upstream as-is with no local validation; supported values depend on the upstream. Example: "float" | | `dimensions` | `integer` | no | The number of dimensions for the output vector, forwarded to the upstream as-is with no local validation; only some models support custom dimensions, and the upstream decides the behavior (typically ignore or error) when unsupported. | | `provider` | `object` | no | Provider routing preferences (order, only, ignore, allow_fallbacks, sort, …). Only forwarded and honored on certain model routes; unsupported routes drop it silently and never send it upstream. | ### cURL ```bash curl https://bazaarlink.ai/api/v1/embeddings \ -H "Authorization: Bearer $BAZAARLINK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/text-embedding-3-small", "input": "The quick brown fox" }' ``` ### Response 200 Success. Returns the OpenAI-compatible shape; data[] corresponds to each input in order, and usage.cost is the amount actually billed for this request. ```json { "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [ 0.0023064255, -0.009327292, 0.015797347 ] } ], "model": "openai/text-embedding-3-small", "usage": { "prompt_tokens": 5, "total_tokens": 5, "cost": 1e-7 } } ``` ### Response 401 Missing Authorization header, or the API key is invalid or disabled. ```json { "error": { "message": "Invalid API key", "type": "invalid_request_error", "code": 401 } } ``` ### Response 402 Insufficient credits, or your weekly/monthly budget cap has been reached. ```json { "error": { "message": "Insufficient credits", "type": "invalid_request_error", "code": 402 } } ``` ### Response 429 Rate limit exceeded (RPM depends on your account tier), or an account-level spend brake has tripped. Retry later. ```json { "error": { "message": "Rate limit exceeded", "type": "invalid_request_error", "code": 429 } } ``` ### Response 503 Service temporarily unavailable — all upstream providers are circuit-broken, the global spend limit tripped, or the service is draining for restart. Retry later. ```json { "error": { "message": "Service temporarily unavailable — global spend limit reached. Try again shortly.", "type": "invalid_request_error", "code": 503 } } ``` ### Response 400 Invalid request — malformed JSON, missing required fields, or failed validation. ```json { "error": { "message": "No route found for model 'unknown/model-name'.", "type": "invalid_request_error", "code": "unknown_model", "param": "model" } } ``` ### Response 403 A Management API Key was used to call this endpoint, or the account is suspended/not found. Management Keys can only call key-management endpoints, not model requests. ```json { "error": { "message": "Management keys cannot make model calls. Use a standard API key.", "type": "invalid_request_error", "code": 403 } } ``` ### Response 404 The model exists in the catalog but currently has no configured, priced route available (a zero-price model). ```json { "error": { "message": "Model has no priced route configured", "type": "model_not_available", "code": "model_not_configured" } } ``` ### Response 410 The model has been retired from the catalog — switch to a newer model ID. ```json { "error": { "message": "Model openai/text-embedding-ada-002 has been retired", "type": "model_not_available", "code": "model_retired" } } ``` ### Response 502 All available upstream providers failed, or the upstream response could not be parsed. Retry shortly. ```json { "error": { "message": "Service temporarily unavailable. Please retry shortly.", "type": "invalid_request_error", "code": 502 } } ``` --- ## GET /api/v1/models **List embedding models** Returns available models, filterable via output_modalities. This is not a dedicated embeddings endpoint — it is the shared model-listing endpoint (GET /api/v1/models); passing output_modalities=embeddings narrows it to embedding models only. When the parameter is omitted, the default returns text models only, not everything. Authentication: Public ### Query parameters | Name | Type | Required | Description | |---|---|---:|---| | `output_modalities` | `string` | no | A single comma-separated string (not repeated same-name query keys), e.g. embeddings or embeddings,image. Pass all to get every modality. Defaults to text only when omitted. Unrecognized values return 400. comma-separated, single value Example: "embeddings" | ### cURL ```bash curl "https://bazaarlink.ai/api/v1/models?output_modalities=embeddings" ``` ### Response 200 Success. data[] contains only models matching the filter; each entry includes pricing (USD per million tokens), context_length, architecture.output_modalities, and related fields. ```json { "object": "list", "data": [ { "id": "text-embedding-3-small", "object": "model", "owned_by": "openai", "name": "OpenAI: text-embedding-3-small", "context_length": 8191, "aliases": [ "openai/text-embedding-3-small" ], "pricing": { "prompt": "0.00000002", "completion": "0" }, "architecture": { "modality": "text->embedding", "input_modalities": [ "text" ], "output_modalities": [ "embeddings" ] } } ] } ``` ### Response 400 Malformed output_modalities — not a single comma-separated string, contains an unrecognized modality value, or exceeds the length limit. ```json { "error": { "message": "output_modalities must be a single comma-separated string", "type": "invalid_request_error", "code": "invalid_output_modalities" } } ``` ### Response 500 An unexpected error occurred while fetching the model catalog. ```json { "error": { "message": "Internal error fetching models", "code": 500 } } ``` --- # Videos ## POST /api/v1/videos **Submit a video generation request** Submits an asynchronous video generation job. Returns 202 immediately with a job id (prefixed vjob_); poll GET /api/v1/videos/{id} until status is completed, then download via unsigned_urls. Billing: credits are reserved at submit from duration × resolution, and settled on the actual delivered seconds (usage.cost in the poll response). Authentication: Bearer API key required ### Request body | Name | Type | Required | Description | |---|---|---:|---| | `model` | `string` | yes | The video generation model ID (provider-qualified). Example: "alibaba/wan2.7-t2v" | | `prompt` | `string` | yes | The text prompt describing the video to generate. | | `duration` | `integer` | no | Video length in seconds. Defaults to 2. Each model has tighter bounds — e.g. reference-to-video (r2v) allows 2–10s; out-of-range values return 400 before any credits are reserved. 1–600 (per-model bounds are tighter; reference-to-video: 2–10) Example: 5 | | `resolution` | `string` | no | Output quality tier, default "720p". Supported tiers vary per model; an unsupported tier returns 400 before any credits are reserved, and the error lists the tiers the model does support. Values: 480p, 720p, 1080p Example: "720p" | | `aspect_ratio` | `string` | no | Aspect ratio. Common values: "16:9", "9:16", "1:1", "4:3", "3:4"; the exact set depends on the model (some also take wide ratios like "21:9"). Unsupported combinations return 400 before credits are reserved; modes that take an input frame derive the ratio from the frame and ignore this field. Values: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 9:21 Example: "16:9" | | `frame_images` | `array` | no | First/last keyframe images (image-to-video, keyframe-to-video). Accepts bare URL strings, or objects { type: "image", image_url: { url }, frame_type: "first" \| "last" }. | | `input_references` | `object[] | string[]` | no | Reference assets (reference-to-video): guide generation with reference items — prefer object form { type: "image", image_url: { url } } (bare URL strings are also accepted and treated as image references). Image references are the most widely supported; audio/video reference objects are forwarded as-is and only take effect on models that support them — other models use the image references and ignore the rest. Only models with an r2v mode accept this field. | | `input_video` | `string | object` | no | Source video (video-edit models only; a BazaarLink extension field). Accepts a URL string, { video_url: { url } }, or { url }. Ignored by non-video-edit models. Editing bills on source seconds + delivered output seconds. | | `generate_audio` | `boolean` | no | Whether to also generate audio. Only effective on audio-capable models; audio seconds bill at a higher per-second rate. | | `watermark` | `boolean` | no | Whether to watermark the output. Defaults to false — BazaarLink actively disables upstream default watermarks unless you explicitly pass true. | | `seed` | `number` | no | Sampling seed. Reproducibility guarantees vary by model. | | `callback_url` | `string` | no | A webhook URL called on the job's terminal state, so you don't have to poll. HTTPS only, and SSRF-checked (private/internal addresses rejected) before any credits are reserved. Fires exactly once, only from the request that wins the terminal-state determination; delivery is retried on failure (2 attempts, 2s/8s backoff), and exhausting retries never affects billing or the job's real status. No signature in v1 — treat the callback as a hint, and confirm status/amount by calling GET /v1/videos/{id} with your API key before acting on it. ⚠️ unsigned_urls in the webhook payload are absolute URLs, unlike the relative paths returned by the poll endpoint. https:// only, ≤2048 chars | ### cURL ```bash curl https://bazaarlink.ai/api/v1/videos \ -H "Authorization: Bearer $BAZAARLINK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "alibaba/wan2.7-t2v", "prompt": "a corgi surfing a wave at sunset", "duration": 5, "resolution": "720p", "aspect_ratio": "16:9" }' ``` ### Response 202 Job accepted (asynchronous). Poll the returned polling_url (i.e. GET /api/v1/videos/{id}) for status; a ≥5s interval is recommended. ```json { "id": "vjob_Xk3fJ9aQ2mB7cD1eF5gH6iJk", "status": "pending", "polling_url": "/api/v1/videos/vjob_Xk3fJ9aQ2mB7cD1eF5gH6iJk" } ``` ### Response 400 Invalid request — malformed JSON, missing required fields, or failed validation. ```json { "error": { "message": "'model' is required.", "type": "invalid_request_error", "code": 400 } } ``` ### Response 401 Missing Authorization header, or the API key is invalid or disabled. ```json { "error": { "message": "Invalid API key", "type": "invalid_request_error", "code": 401 } } ``` ### Response 402 Insufficient credits, or your weekly/monthly budget cap has been reached. ```json { "error": { "message": "Insufficient credits", "type": "invalid_request_error", "code": 402 } } ``` ### Response 429 Rate limit exceeded (RPM depends on your account tier), or an account-level spend brake has tripped. Retry later. ```json { "error": { "message": "Rate limit exceeded", "type": "invalid_request_error", "code": 429 } } ``` ### Response 503 Service temporarily unavailable — all upstream providers are circuit-broken, the global spend limit tripped, or the service is draining for restart. Retry later. ```json { "error": { "message": "Service temporarily unavailable — global spend limit reached. Try again shortly.", "type": "invalid_request_error", "code": 503 } } ``` ### Response 404 The requested resource was not found — the ID does not exist or does not belong to this key. ```json { "error": { "message": "Unknown model: alibaba/wan99-t2v", "type": "invalid_request_error", "code": 404 } } ``` ### Response 410 The model has been retired from the catalog — switch to a newer model ID. ```json { "error": { "message": "Model retired.", "type": "model_not_available", "code": 410 } } ``` --- ## GET /api/v1/videos/:id **Get video generation status** Polls a video job. The only terminal states are completed / failed; while running you will usually see pending / processing, but upstream in-flight labels (e.g. in_progress) may pass through — write your loop as "until completed or failed" rather than enumerating intermediate states. Upstream cancellations/expiries (cancelled / expired) surface as failed with the reserved credits refunded. On completed, unsigned_urls lists downloadable content paths and usage.cost is the final charge (billed on actual delivered seconds); on failed, error explains why. Upstream checks are throttled to one per 8s server-side; poll at a ≥5s interval. Authentication: Bearer API key required ### Path parameters | Name | Type | Required | Description | |---|---|---:|---| | `id` | `string` | yes | The job id returned at submit (prefixed vjob_). Only jobs owned by the same account are visible. Example: "vjob_Xk3fJ9aQ2mB7cD1eF5gH6iJk" | ### cURL ```bash curl https://bazaarlink.ai/api/v1/videos/vjob_Xk3fJ9aQ2mB7cD1eF5gH6iJk \ -H "Authorization: Bearer $BAZAARLINK_API_KEY" ``` ### Response 200 Success. The example shows a completed job; pending / processing responses omit unsigned_urls and usage, and failed adds an error field. unsigned_urls are relative paths — GET them with the same API key to download. ```json { "id": "vjob_Xk3fJ9aQ2mB7cD1eF5gH6iJk", "status": "completed", "polling_url": "/api/v1/videos/vjob_Xk3fJ9aQ2mB7cD1eF5gH6iJk", "unsigned_urls": [ "/api/v1/videos/vjob_Xk3fJ9aQ2mB7cD1eF5gH6iJk/content?index=0" ], "usage": { "cost": 0.5, "is_byok": false } } ``` ### Response 401 Missing Authorization header, or the API key is invalid or disabled. ```json { "error": { "message": "Invalid or disabled API key.", "type": "invalid_request_error", "code": 401 } } ``` ### Response 404 The requested resource was not found — the ID does not exist or does not belong to this key. ```json { "error": { "message": "Job not found.", "type": "invalid_request_error", "code": 404 } } ``` --- ## GET /api/v1/videos/:id/content **Download the generated video** Streams the generated video bytes (typically video/mp4). The unsigned_urls in the poll response point here. Supports HTTP Range (Accept-Ranges: bytes, 206 partial content) — mobile-browser