Tài liệu API

Tài liệu cho nhà phát triển

Tài liệu công khai cho tích hợp XVAPI. Hãy dùng một miền API ổn định, tên mô hình công khai ổn định và thanh toán qua ví.

Tóm tắt tích hợp

Base URL: https://api.xvapi.com/v1
Tên thay thế: Tên công khai ổn định
Hỗ trợ: ops@xvapi.com
Cập nhật lần cuối: 2026-09-12
Phiên bản: v2026.09.12

Lịch sử thay đổi tài liệu

v2026.09.12·2026-09-12

Public documentation audit

Reviewed public endpoints, field-level contracts, and response examples against the current API surface.
Clarified image options, multipart upload limits, and retry behavior for application developers.

Tổng quan tài liệu

API reference, integration guidance, and error recovery

Build against the public `/v1` contract: authenticate safely, discover available models, send valid requests, process responses, and recover from documented failures.

Lộ trình đọc

Quick start: For authentication, base URL, and a first successful request.
Troubleshooting: For status codes, rate limits, access, and retry decisions.
Image API: For generation, edits, parameters, and result handling.

Bắt đầu từ đây

Start from the capability you need to integrate

I want to make a first API call

Start with the Base URL, Bearer authentication, and a small documented request.

Read quickstart↗

I need to diagnose a failed request

Use status codes and retry guidance to determine whether to correct, wait, or contact support.

Open troubleshooting↗

I need image generation or editing

Choose the generation or edit endpoint, validate parameters, and handle `data` results safely.

Read Image API↗

Overview

What your customers integrate with

Your public API should look simple from the outside: one auth model, one customer wallet system, and stable public model aliases.

Stable public domain

Keep a stable public contract so every client integration can stay predictable.

One auth standard

Use one API key format for every documented endpoint.

Wallet settlement + tracing

Every request should be traceable through logs and wallet settlement events.

Quickstart

Get to the first successful call in minutes

The public integration path should be short: create an account, top up balance, issue a key, pick a model name, and call one endpoint.

1Create an account and top up wallet balance.
2Issue a customer-facing API key from your platform.
3Choose a stable public model name from your model list.
4Call the target endpoint and verify the first successful response.

First successful request

BASE_URL="https://api.xvapi.com/v1"
AUTH_HEADER="Authorization: Bearer YOUR_XVAPI_API_KEY"

curl $BASE_URL/chat/completions \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      { "role": "system", "content": "You are a concise assistant." },
      { "role": "user", "content": "Say hello." }
    ],
    "temperature": 0.7
  }'

SDK Examples

Use official SDKs with the XVAPI base URL

Most clients can keep their SDK usage pattern and only switch the API key. Start from the Responses API unless you need classic chat-completions compatibility.

JavaScript / TypeScript

import OpenAI from "openai";

const BASE_URL = "https://api.xvapi.com/v1";

const client = new OpenAI({
  apiKey: "YOUR_XVAPI_API_KEY",
  baseURL: BASE_URL,
});

const response = await client.responses.create({
  model: "gpt-4.1-mini",
  input: "Write a short launch checklist."
});

console.log(response.output_text);

Python

from openai import OpenAI

BASE_URL = "https://api.xvapi.com/v1"

client = OpenAI(
    api_key="YOUR_XVAPI_API_KEY",
    base_url=BASE_URL,
)

response = client.responses.create(
    model="gpt-4.1-mini",
    input="Write a short launch checklist."
)

print(response.output_text)

Image API

Send your first image generation request

Start with `/v1/models`, select an image-capable public alias, then send one small request to `/v1/images/generations` and inspect the returned data item.

When you need this

You need a first successful image request before adding advanced options.
You need to confirm that the current API key can list an image-capable model.
You want to distinguish generation requests from reference-image edits.

Before you start

Store an XVAPI API key in your server-side environment, not in browser code.

Call `/v1/models` with that key before hard-coding a model name.

Use one image and documented options for the first request.

1. Discover an image model

Call `/v1/models` and select an alias whose metadata declares image-generation capabilities.

2. Send one small request

POST to `/v1/images/generations` with model, prompt, and one supported size or quality option.

3. Inspect the response

Read the first item in data and handle the URL or base64 payload returned for that model.

4. Add options gradually

Only after the baseline succeeds should you add n, quality, size, or reference-image editing.

Most common mistakes

The model list appears, so the request must work

Not necessarily. Listing a model and successfully calling that model are two different checks. A model can remain visible while its current service configuration is unavailable.

Putting an API key in browser code

Do not expose API keys in browser code or public repositories. Keep keys in your application's server-side environment.

Start with multi-image generation

That makes debugging harder. First verify one-image generation. Only after that should you try multi-image or reference-image flows.

What to do next

If verification succeeds but generation still fails, continue with the troubleshooting article about timeouts and model availability.

If you plan to use reference images, move on to the guide about the edits workflow rather than repeating plain generation.

If you are unsure which image model to keep public, review the model guide before exposing more aliases.

Review quickstart Review API Key Rules View Models

Image Edits API

Edit an image with a reference file

Use `/v1/images/edits` when an edit depends on a reference file. Use `/v1/images/generations` for a new image created from a text prompt.

When reference images make sense

You want the output to stay close to an existing composition, subject, or product shot.

You need edits and variations around one base image instead of a fully fresh generation.

You want to test whether the current image model supports edits instead of plain image generation only.

What changes after upload

1Send a multipart/form-data request to `/v1/images/edits`.
2Attach the reference file in `image` and state the requested change in `prompt`.
3Read the returned `data` item exactly as you would for image generation.

1. Upload a single clear reference

Start with one image that expresses the key composition or subject. A noisy or irrelevant reference makes debugging harder.

2. Keep the first edit request simple

Use a short prompt that clearly describes what should change. Do not combine too many style and structure instructions in the first attempt.

3. Verify that the model supports edits

Some image models support generation but not edits. If upload works but generation fails, check edit support separately.

4. Use the generation endpoint for a new image

Do not attach an image to `/v1/images/generations`; use its JSON request body for text-to-image creation.

Common mistakes

Treating the reference image like a decorative attachment

Once a reference is attached, it changes the request mode. It is not a passive asset sitting next to the prompt.

Using multi-image generation before the edit path is stable

The reliable order is plain single-image generation first, then single-image edit flow, and only after that more complex batches.

Leaving the reference attached and forgetting why the output changed

If the result suddenly starts following an older image, check whether the reference thumbnail is still present.

What to open next

If the edit request times out, go back to the timeout troubleshooting section and treat the edit path separately from plain generation.

If the model is listed but edits still fail, review the article about visible models that fail at call time.

If you want more predictable results, tune aspect ratio and quality only after the first edit request succeeds.

Read Image Edits API Read Images API Open timeout guide

Image API

How to choose the right aspect ratio for image generation

Aspect ratio should follow the destination of the image, not guesswork. Picking the right frame first reduces wasted generations and makes prompt debugging much simpler.

Choose by destination first

Use 1:1 when the image must work as a neutral square asset, such as a grid card or catalog tile.

Use 4:5 or 2:3 when the image is meant for posters, article covers, or vertically cropped feeds.

Use 9:16 for phone-first or story-like layouts where the full frame is tall.

Use 16:9 or 21:9 only when the final output really needs a wide scene, banner, or cinematic crop.

Practical mapping

1:1

Square product cards, generic thumbnails, neutral prompt testing.

4:5

Social posts, editorial portrait crops, marketplace covers.

2:3

Poster-style output, print-like verticals, fashion/editorial drafts.

9:16

Mobile-first layouts, story covers, tall scene compositions.

3:2 / 5:4

Balanced horizontal compositions with less cinematic width.

16:9 / 21:9

Wide scenic shots, banners, cinematic frames, hero imagery.

Pick ratio before changing the prompt

If you change both ratio and prompt complexity at the same time, you will not know what actually caused the visual shift.

Start from the final crop

Work backward from where the image will be used. Do not generate a wide image if the final slot is a phone portrait card.

Use Auto only when the model is still unknown

Auto is useful when you want to check whether the selected model works at all, but it is not a substitute for choosing a production ratio.

Image API

What the quality option actually changes

The quality switch is not a magic beauty filter. It changes the tradeoff between cost, latency, and the chance of getting a stable image result.

Standard

Use this when you are testing prompts, ratios, or model availability for the first time.

It is usually the best baseline for debugging because the request is cheaper and often returns faster.

If even standard quality is unstable, high quality will not fix a model availability problem.

High quality

Use high quality only after the prompt, ratio, and model already behave the way you expect.

Expect a slower response and a higher chance of timeout under weak model service conditions.

High quality plus multi-image generation is the most expensive and least stable combination in a slow route.

Use standard to debug the route

Do not diagnose timeout, budget, or permission issues while also increasing quality. Keep the request simple first.

Upgrade quality after the first acceptable result

Once you have a composition that works, quality becomes an optimization step rather than a debugging variable.

Treat quality as a workflow decision

Standard is for exploration; high quality is for final output when the selected model is already trustworthy.

Image Results

Process and persist returned image data

A successful image response returns result items in `data`. Your application should validate the response, retain the data it needs, and store important assets in its own storage.

Read each result item

URL: retrieve the returned URL promptly and store a durable copy when your product requires one.

Base64: decode and store the payload using your application's normal binary-data handling.

Request context: retain the public model name and prompt when your product needs reproducible work.

Errors: persist the status code and request timestamp, never an API key or authorization header.

Storage responsibilities

Treat response data as an integration result, not as your application's archive.

Use your own object storage and access control for assets that must persist or be shared.

Keep only the data required by your product and applicable privacy policy.

Persist results deliberately

Move important assets to storage controlled by your application before presenting them to end users.

Keep reproducibility data minimal

Store the model alias, prompt, parameters, and request time only when they are necessary for your product.

Do not expose credentials in result flows

Sanitize client logs and support tickets so API keys and Authorization headers never enter your stored records.

Authentication

Use one key standard across every public endpoint

Send an XVAPI API key only from a trusted server-side environment. Do not embed it in browser code, mobile binaries, or public repositories.

Key scope

Bind keys to package permissions, wallet rules, and request logs.

Header rule

Every public endpoint uses the same Bearer key format. Send the key only from your application's trusted environment.

API Keys

Treat customer API keys as your public contract

Applications need an XVAPI key, their current package access, and the public model list returned for that key.

Issue customer-facing API keys from your platform and send them only from trusted server-side environments.
Restrict keys by package access and optional model allow-lists when needed.
Revoke leaked or temporary keys immediately and re-issue a new key instead of reusing credentials.

Key usage pattern

Use the same customer-facing API key across the public model catalog, chat, embedding, image, and transcription endpoints.

Authorization: Bearer YOUR_XVAPI_API_KEY

Conventions

Keep the public API stable over time

Single public base URL

Expose one stable API domain so every client integration stays predictable.

Customer-owned API keys

Issue your own keys and bind them to balance, package permissions, and request logs.

Stable public model aliases

Keep public model names stable so clients and automation can keep working over time.

GET/v1/models

Models

Return the current public model catalog that the caller can actually use under their package and API key rules.

Endpoint công khai

Ghi chú yêu cầu

This endpoint already filters by account access, API key model allow-list, disabled pricing items, and currently available model entries.
Use it before building model pickers or caching a catalog on the client side.
Metadata includes billing type, label, and the public usage context for the alias.

Ví dụ yêu cầu

curl $BASE_URL/models \
  -H "$AUTH_HEADER"

Cấu trúc phản hồi

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4.1-mini",
      "object": "model",
      "root": "gpt-4.1-mini",
      "metadata": {
        "label": "GPT-4.1 Mini",
        "billing_type": "token"
      }
    }
  ]
}

Hợp đồng công khai

Dùng các trường và giới hạn này làm ranh giới tích hợp công khai.

TrườngVị tríBắt buộcKiểuMô tả / giới hạn

Endpoint này không yêu cầu thân yêu cầu.

Header

AuthorizationBearer token issued by XVAPI.

Ghi chú phản hồi

Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
The list is already filtered by the caller's account and API key access.
Image models may include metadata.image_generation with supported sizes, qualities, and native 4K support.

Hướng dẫn thử lại

Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.

POST/v1/chat/completions

Chat Completions

Classic OpenAI-compatible conversational entry for most SDKs and legacy integrations.

Endpoint công khai

Ghi chú yêu cầu

Use when your client already targets OpenAI chat-completions semantics.
Supports stable public model names across your integrations.
Billing and request logs are recorded together for each request.

Ví dụ yêu cầu

{
  "model": "gpt-4.1-mini",
  "messages": [
    { "role": "system", "content": "You are helpful." },
    { "role": "user", "content": "List three launch checks." }
  ],
  "temperature": 0.6,
  "stream": false
}

Cấu trúc phản hồi

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "model": "gpt-4.1-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "1. Verify wallet balance..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 62,
    "total_tokens": 90
  }
}

Hợp đồng công khai

Dùng các trường và giới hạn này làm ranh giới tích hợp công khai.

TrườngVị tríBắt buộcKiểuMô tả / giới hạn

modelThân JSONCóstringStable public model alias.

messagesThân JSONCóarrayNon-empty messages array with role and content values.

temperatureThân JSONKhôngnumberSampling control forwarded to the selected model.

max_tokensThân JSONKhôngintegerMaximum number of output tokens the model may generate.

streamThân JSONKhôngbooleanWhen true, returns an SSE stream.

reasoning_effortThân JSONKhôngstringOptional reasoning effort hint for models that support it.

Header

AuthorizationBearer token issued by XVAPI.

Content-TypeUse application/json for JSON request bodies.

Ghi chú phản hồi

Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
Non-stream responses keep the chat.completion shape with choices and usage.
Streaming responses are server-sent events; consume chunks until the stream closes.

Hướng dẫn thử lại

Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.

POST/v1/responses

Responses

Unified response surface for newer OpenAI SDKs and workflows that want one modern output object.

Endpoint công khai

Ghi chú yêu cầu

Preferred for new clients that already use the Responses API shape.
Supports simpler text generation and unified output parsing.
Uses the same API key and billing rules as every other public endpoint.

Ví dụ yêu cầu

{
  "model": "gpt-4.1-mini",
  "input": "Write a short release note for a new model launch."
}

Cấu trúc phản hồi

{
  "id": "resp_xxx",
  "object": "response",
  "model": "gpt-4.1-mini",
  "output_text": "We added a new model...",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 48,
    "total_tokens": 60
  }
}

Hợp đồng công khai

Dùng các trường và giới hạn này làm ranh giới tích hợp công khai.

TrườngVị tríBắt buộcKiểuMô tả / giới hạn

modelThân JSONCóstringStable public model alias.

inputThân JSONCóstring | object | arrayInput content for the requested response.

instructionsThân JSONKhôngstringOptional instruction text.

max_output_tokensThân JSONKhôngintegerMaximum output token budget.

streamThân JSONKhôngbooleanWhen true, returns a streamed response.

reasoning.effortThân JSONKhôngstringOptional reasoning effort hint.

reasoning_effortThân JSONKhôngstringCompatibility alias for reasoning.effort.

metadataThân JSONKhôngobjectOptional caller metadata.

toolsThân JSONKhôngarrayOptional tool definitions forwarded to the selected model.

Header

AuthorizationBearer token issued by XVAPI.

Content-TypeUse application/json for JSON request bodies.

Ghi chú phản hồi

Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
The public response uses the Responses-compatible object returned by the selected model service.

Hướng dẫn thử lại

Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.

POST/v1/embeddings

Embeddings

Vector generation for semantic search, RAG indexing, reranking preparation, and retrieval workflows.

Endpoint công khai

Ghi chú yêu cầu

Send one string or a list of strings in input.
Embedding requests are billed through the same wallet and usage records.
Best used with stable public model names.

Ví dụ yêu cầu

{
  "model": "text-embedding-3-small",
  "input": [
    "xvapi gateway",
    "wallet settlement flow"
  ]
}

Cấu trúc phản hồi

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.012, -0.074, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 14,
    "total_tokens": 14
  }
}

Hợp đồng công khai

Dùng các trường và giới hạn này làm ranh giới tích hợp công khai.

TrườngVị tríBắt buộcKiểuMô tả / giới hạn

modelThân JSONCóstringStable public embedding model alias.

inputThân JSONCóstring | string[]One text value or a list of text values.

encoding_formatThân JSONKhôngstringOptional embedding encoding format.

dimensionsThân JSONKhôngintegerOptional output dimensions when supported by the model.

Header

AuthorizationBearer token issued by XVAPI.

Content-TypeUse application/json for JSON request bodies.

Ghi chú phản hồi

Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
The response contains one embedding item per input value and usage token counts.

Hướng dẫn thử lại

Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.

POST/v1/images/generations

Image Generations

Public image generation endpoint with your own pricing, logs, and available model catalog.

Endpoint công khai

Ghi chú yêu cầu

Use for text-to-image generation from the same public API surface.
Image requests consume balance from the same wallet system.
Keep image model names stable for clients and automation.

Ví dụ yêu cầu

{
  "model": "gpt-image-1",
  "prompt": "A futuristic API operations dashboard in soft blue lighting",
  "size": "1024x1024"
}

Cấu trúc phản hồi

{
  "created": 1712345678,
  "data": [
    {
      "url": "https://api.xvapi.com/images/req_xxx.png"
    }
  ]
}

Hợp đồng công khai

Dùng các trường và giới hạn này làm ranh giới tích hợp công khai.

TrườngVị tríBắt buộcKiểuMô tả / giới hạn

modelThân JSONCóstringPublic image model alias.

promptThân JSONCóstringText description for the generated image.

sizeThân JSONKhôngstringRequested canvas size.Must be listed in the selected model's supported_sizes metadata.

qualityThân JSONKhôngstringRequested image quality or resolution tier.Use auto, low, medium, high, 1k, 2k, or 4k; the selected model still decides what is available.

nThân JSONKhôngintegerNumber of images to generate.Integer from 1 to 4; defaults to 1.

response_formatThân JSONKhôngstringPreferred image result encoding.Use a format supported by the selected model. Results may contain a URL or base64 payload.

userThân JSONKhôngstringOptional caller-provided user identifier.

Header

AuthorizationBearer token issued by XVAPI.

Content-TypeUse application/json for JSON request bodies.

Ghi chú phản hồi

Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
The data array contains the generated image results. Each result may expose a URL or a base64 payload depending on the selected model and response_format.

Hướng dẫn thử lại

Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.

POST/v1/images/edits

Image Edits

Image editing endpoint for reference-image workflows. Use multipart form-data when the request includes an input image.

Endpoint công khai

Ghi chú yêu cầu

Use this endpoint when the client uploads a reference image and wants the model to edit or transform it.
Submit multipart form-data with model, prompt, and image fields.
Edits use the same API key, model access, budget, wallet reservation, and request logging rules as image generation.

Ví dụ yêu cầu

curl $BASE_URL/images/edits \
  -H "$AUTH_HEADER" \
  -F model="gpt-image-1" \
  -F prompt="Turn this product photo into a clean catalog image" \
  -F image="@reference.png" \
  -F size="1024x1024"

Cấu trúc phản hồi

{
  "created": 1712345678,
  "data": [
    {
      "url": "https://api.xvapi.com/images/edit_req_xxx.png"
    }
  ]
}

Hợp đồng công khai

Dùng các trường và giới hạn này làm ranh giới tích hợp công khai.

TrườngVị tríBắt buộcKiểuMô tả / giới hạn

modelmultipartCóstringPublic image edit model alias.

promptmultipartCóstringInstruction describing the requested edit.

imagemultipartCófileReference image uploaded with the request.PNG, JPEG, or WebP only; maximum 8 MB; the file signature must match its MIME type.

sizemultipartKhôngstringRequested output size.Must be supported by the selected model.

qualitymultipartKhôngstringRequested output quality or resolution tier.The selected model must support the requested tier.

nmultipartKhôngintegerNumber of edited images.Integer from 1 to 4; defaults to 1.

response_formatmultipartKhôngstringPreferred edited-image result encoding.Use a format supported by the selected model.

usermultipartKhôngstringOptional caller-provided user identifier.

Header

AuthorizationBearer token issued by XVAPI.

Content-TypeUse multipart/form-data; let the client generate the boundary.

Ghi chú phản hồi

Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
The data array contains edited image results and may expose URL or base64 output according to the selected model.

Hướng dẫn thử lại

Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.

POST/v1/audio/transcriptions

Audio Transcriptions

Speech-to-text transcription endpoint for uploaded audio files with the same auth and billing flow.

Endpoint công khai

Ghi chú yêu cầu

Current public audio entry focuses on transcription workflows.
Upload multipart form-data with file and model fields.
Requests are logged and billed under the same customer account.

Ví dụ yêu cầu

curl $BASE_URL/audio/transcriptions \
  -H "$AUTH_HEADER" \
  -F file="@meeting.mp3" \
  -F model="gpt-4o-mini-transcribe"

Cấu trúc phản hồi

{
  "text": "Today we reviewed the gateway release checklist..."
}

Hợp đồng công khai

Dùng các trường và giới hạn này làm ranh giới tích hợp công khai.

TrườngVị tríBắt buộcKiểuMô tả / giới hạn

modelmultipartCóstringPublic transcription model alias.

filemultipartCófileAudio file to transcribe.Use a file format accepted by the selected transcription model. Start with a small file when integrating a new model.

languagemultipartKhôngstringOptional language hint.

promptmultipartKhôngstringOptional context or vocabulary hint.

response_formatmultipartKhôngstringRequested transcription response format.Use a value supported by the selected transcription model.

temperaturemultipartKhôngnumberOptional transcription sampling control.

Header

AuthorizationBearer token issued by XVAPI.

Content-TypeUse multipart/form-data; let the client generate the boundary.

Ghi chú phản hồi

Responses use JSON unless the endpoint explicitly documents a streaming or multipart flow.
The normalized public response contains the transcribed text under text.

Hướng dẫn thử lại

Retry 429 only after applying backoff. When Retry-After is present, wait at least that many seconds.
Do not blindly retry 400, 401, 402, or 403 responses; fix the request, key, balance, or access rule first.
A 502/503 may be temporary, but retry with bounded exponential backoff and keep the same public model name.

Model Fields

Understand the public fields returned by /v1/models

The public model catalog is the contract your clients should build against. Use stable aliases and inspect metadata before enabling optional model-specific parameters.

FieldTypeMeaning

idstringStable public model alias used by clients.

objectstringAlways `model` for each item in the list.

rootstringThe canonical alias root exposed publicly.

metadata.labelstringHuman-readable model name for UI display.

metadata.billing_typestringHow the model is billed on your platform.

Model Catalog

Public model names should stay stable

Clients should integrate against the public model catalog. Resolve a model from `/v1/models` before enabling it in an application.

What customers see

gpt-4.1-minigpt-image-1text-embedding-3-smallgpt-4o-mini-transcribe

What the platform can adjust safely

Model availability by region and plan
Availability and retry policy
Pricing adjustments and package permissions

Streaming

Streaming support is endpoint-specific

XVAPI does not expose the same streaming behavior on every endpoint. Document the real surface clearly so customer SDKs behave predictably.

Responses stream

Use `stream: true` on `/v1/responses` when your client expects SSE output. XVAPI keeps reservation, settlement, and tracing consistent across the stream lifecycle.

Responses stream example

{
  "model": "gpt-4.1-mini",
  "input": "List the launch checks step by step.",
  "stream": true
}

Current public rule

Chat Completions supports streaming

Use `stream: true` when you want SSE output on `/v1/chat/completions`. XVAPI keeps reservation, settlement, and tracing consistent across the stream lifecycle.

Recommended rule: use `/v1/responses` for modern response-shaped clients, and keep `/v1/chat/completions` for classic SDK compatibility.

Billing & Wallet

Public billing should follow your own wallet system

A reliable API business needs clear wallet semantics: reserve, settle, release, and trace every request back to a log.

Pre-check

Verify balance and package access before the request starts.

Reserve

Create a customer-facing balance hold when needed.

Settle

Write final billing after usage is known.

Trace

Link every charge to a request log and wallet event.

Limits & Budgets

Every request also passes rate, package, and budget checks

Public requests are subject to rate limits, model access control, package rules, wallet pre-reservation, and user budget policies before final settlement.

Rate limit

Per-account and per-key limits are checked before model execution.

Model access

Package rules and API key model allow-lists both affect what the caller can use.

Budget policy

Estimated request cost is checked against user budget policy before reservation.

Reservation flow

Wallet and key budgets reserve first, then settle or release after the model result returns.

Troubleshooting

Why image generation times out and where to check first

Image generation can take longer than text requests. Handle timeout and availability errors by status code, then retry only the failures that are documented as transient.

Safe recovery sequence

1Record the public endpoint, model alias, status code, and request time. Do not record API keys or Authorization headers.
2For 429, honor Retry-After when present before retrying.
3For 502 or 503, retry with bounded exponential backoff and keep the request idempotent where possible.
4For 400, 401, 402, or 403, correct the request, credentials, balance, or access before sending it again.

When to contact support

The same 5xx response persists after a bounded retry sequence.

You need help interpreting a request result after removing API keys, authorization headers, and personal data.

Include the endpoint, public model alias, status code, and request time in the support request.

For a new image integration, reduce the first request to one image and a documented size before adding options.

Bounded retries only

Set a small retry limit and exponential delay so temporary errors do not create duplicate cost or overload your application.

Do not retry client errors

Fix 400, 401, 402, and 403 responses before sending another request. Repeating the same request will not resolve them.

Build a minimal reproduction

For image requests, reproduce an issue with one image, one public alias, and documented parameters before adding complexity.

Troubleshooting

Why a model can appear in the list but still fail at call time

Model visibility and model availability are not the same thing. A model name in `/v1/models` is only one part of the public contract.

What “visible” usually proves

The public model catalog returned that model name through `/v1/models`.

The public catalog still exposes that alias.

The caller can see the model entry in a selector or list.

What “callable” still depends on

The current key is actually allowed to use that model.

Package rules, allow-lists, wallet, and budget checks all let the request continue.

The public alias still points to a valid model configuration.

The selected model service can answer a normal request instead of only appearing in the catalog.

Recommended debug order

1Confirm that the current key can still list at least one usable model through your own `/v1/models` surface.
2Check whether the failed model is blocked by package rules, allow-lists, or wallet / budget policy.
3Verify that the public alias still points to the intended model instead of a stale configuration.
4If the model is visible but still fails, send one small normal request before trying more complex parameters.

Errors

Explain failures in a way support can act on

CodeMeaning

400Bad request shape, missing fields, invalid JSON, or unsupported parameter combinations.

401Missing or invalid API key. Always verify the Bearer token first.

402Insufficient wallet balance or the current billing rule denied the request.

403Your account, package, or model permissions do not allow this request.

429The current account or API key has hit a rate or concurrency limit.

500Temporary service error. Record the request time and model, then contact support if the error continues.

502/503A requested capability is temporarily unavailable. Retry later with bounded exponential backoff.

400 · Missing required fields

{
  "error": {
    "message": "model and messages are required"
  }
}

401 · Invalid API key

{
  "error": {
    "message": "Invalid API key"
  }
}

402

Insufficient balance

{
  "error": {
    "message": "Insufficient wallet balance"
  }
}

429

Rate limit hit

{
  "error": {
    "message": "Rate limit exceeded"
  }
}

403

Model not allowed

{
  "error": {
    "message": "Model not allowed for current package"
  }
}

503

Image generation temporarily unavailable

{
  "error": {
    "message": "Image generation is temporarily unavailable. Please retry or choose another model."
  }
}

Retry policy

Error handling by category

A status code alone is not enough. Follow the category-specific action before deciding whether to retry.

400Do not retry

Request validation

The request body is malformed, missing a required field, or asks for an unsupported option.

Action: Fix the request shape or parameter before sending it again.

401/402/403Do not retry

Authentication, balance, or access

The key, wallet, package, budget policy, or model access rule stopped the request.

Action: Fix the credential, balance, package, budget, or model permission first.

429Retry after backoff

Rate or concurrency limit

The account or API key has reached a request limit. The platform may include Retry-After.

Action: Wait, honor Retry-After when present, then retry with bounded backoff.

500Conditional

Platform error

The platform could not complete the request after its normal checks.

Action: Do not loop aggressively. Check the request time, model, and support logs.

502/503Conditional

Temporary model service failure

The selected model service may be unavailable, degraded, or timed out.

Action: Retry with bounded exponential backoff and keep the same public model alias.

FAQ & Support

Most support issues come down to billing, limits, or model access

Which API domain should my application call?

Use the public Base URL shown in this document together with an API key issued for your XVAPI account.

How should pricing be explained?

Explain wallet balance, model unit pricing, and settlement rules clearly from the customer perspective.

What should support check first when a call looks wrong?

Request logs, wallet events, model name, request time, and whether the problem is billing or latency.

Can a public model name remain stable when services change?

Yes. Keep the public model name stable so clients do not need to change their integration.