API Documentation

01 / Get started

Get started

Complete these steps in order. You can test the connection as soon as you have an API key and a model name.

  1. 01

    Register or sign in

    Create an account or sign in to an existing account before using the API.

  2. 02

    Balance

    Keep enough balance before production traffic

  3. 03

    Create an API key

    Open the console, create a key for your application, and keep the full value private.

  4. 04

    Choose a model

    Compare available models, then select an exact model ID that your account can use.

  5. 05

    Send your first request

    Replace the key and model placeholders in one of the examples below and run it.

  6. 06

    Usage and billing

    Review usage logs, quota, costs, and payment status from the console.

Next step

After creating a key, continue with the API basics and copy the example that matches your client.

API Keys

User guide

Loading...

User guide

Loading...

User guide

Loading...

User guide

Loading...

User guide

Loading...

User guide

Loading...

User guide

Loading...

02 / API

API Basics

Use the service address, API key, and model ID below as the three values shared by every client.

Base URL

https://api.flowvision.tech

Use the service address shown here. Do not include the documentation page path.

Authentication

Authorization: Bearer sk-your-api-key

Create the key in the console and send it with every API request.

Model name

your-model

Use the exact model ID returned by the model list.

API Basics

Available Models

Use this request to see the model IDs available to your API key.

Example request
curl https://api.flowvision.tech/v1/models \
  -H "Authorization: Bearer sk-your-api-key"
Browse available models and pricing

API Basics

API Requests

Use the format that matches your client. Enable only the upstream models and protocols configured by your administrator.

OpenAI Chat Completions

/v1/chat/completions

OpenAI Responses

/v1/responses

Anthropic

/v1/messages

Gemini

/v1beta/models/{model}:generateContent

Image

/v1/images/generations

Video

/v1/videos

Rerank

/v1/rerank

Embeddings

/v1/embeddings

Audio

/v1/audio/speech
See Model Square for available models.

03 / Requests

Request formats

Choose the format supported by your client. All formats use the same FlowVision key.

For Anthropic clients, x-api-key is accepted. Bearer authentication is also supported.

Request formats

OpenAI Chat Completions format

Use a messages array for standard chat requests.

OpenAI Chat Completions format
curl https://api.flowvision.tech/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

Request formats

OpenAI Responses format

Use input for Responses requests, including Codex.

OpenAI Responses format
curl https://api.flowvision.tech/v1/responses \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "input": "Hello",
    "max_output_tokens": 128
  }'

Request formats

Anthropic Messages format

Use messages together with max_tokens for Claude clients.

Anthropic Messages format
curl https://api.flowvision.tech/v1/messages \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "max_tokens": 128,
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

For Anthropic clients, x-api-key is accepted. Bearer authentication is also supported.

04 / Models

Model usage by scenario

Use the guide below to choose the right API shape for conversational and video models.

Use the FlowVision API key created in the console. End users do not need upstream provider credentials.

Model usage by scenario

Conversational models

Use Chat Completions for ordinary conversational requests.

Recommended endpoint

POST /v1/chat/completions

Example model ID

deepseek-v4-flash-ga-260731
Chat request
curl https://api.flowvision.tech/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-ga-260731",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain what FlowVision does in one sentence."}
    ],
    "temperature": 0.7
  }'

The model ID is an example. Replace it with an id returned by /v1/models.

Use /v1/responses for Responses clients such as Codex CLI.

Model usage by scenario

Video models · Seedance

Video generation is asynchronous. Save the task ID and poll until the task is complete.

Recommended endpoint

POST /v1/video/generations

Example model ID

doubao-seedance-2-0-260128
Seedance text-to-video request
curl https://api.flowvision.tech/v1/video/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "A ginger cat walking through a sunny courtyard, cinematic camera movement",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "output_format": "mp4",
    "generate_audio": true,
    "watermark": false
  }'

Request parameters

prompt
Prompt text that describes the video to generate.
duration
Duration in seconds; supported values are 4–15 for most Seedance models and 4–30 for Seedance 2.5.
ratio
Output ratio, such as 16:9 or 9:16.
resolution
Output resolution; 720p is a safe default.
output_format
Output format; mp4 is supported by all Seedance models.
generate_audio
Whether to generate audio; defaults to true.
watermark
Whether to add a watermark; defaults to false.

For image-to-video, add references with an HTTPS image_url; video_url and audio_url are supported when the selected model allows them.

Check video task status
curl https://api.flowvision.tech/v1/video/generations/task_xxx \
  -H "Authorization: Bearer sk-your-api-key"

curl https://api.flowvision.tech/v1/videos/task_xxx/content \
  -H "Authorization: Bearer sk-your-api-key" \
  -o output.mp4

Use the returned task ID to check progress. A completed task can be downloaded from the content endpoint.

05 / Client setup

Codex CLI

Use the OpenAI Responses protocol with FlowVision as a custom provider.

The API key used here is issued by FlowVision. It is not an upstream provider key.

1. Add the provider

Save this configuration in your Codex config file: ~/.codex/config.toml

Codex configuration
model = "your-model"
model_provider = "flowvision"

[model_providers.flowvision]
name = "FlowVision-Api"
base_url = "https://api.flowvision.tech/v1"
env_key = "FLOWVISION_API_KEY"
wire_api = "responses"

2. Set the API key

Set the environment variable before starting Codex.

Environment variable
export FLOWVISION_API_KEY="sk-your-api-key"
codex

Use the exact model ID returned by the model list. The provider URL in the configuration includes the API version path.

Add models without replacing existing models

Merge available models into your Codex catalog, back up your configuration, then restart Codex. Model access depends on your API key and channel support.

Codex configuration
model_catalog_json = "/absolute/path/flowvision-models.json"
Download model catalog setup guide (Chinese)

06 / Client setup

Claude Code

Claude Code uses the Anthropic Messages format and reads its connection settings from environment variables.

Base URL

https://api.flowvision.tech

Do not add the API version suffix to this value.

API key

ANTHROPIC_API_KEY

Use the key created in Console → API Keys.

Model name

ANTHROPIC_MODEL

Set this to an exact model ID available to your key.

Set these variables before starting Claude Code.

Claude Code configuration
export ANTHROPIC_BASE_URL="https://api.flowvision.tech"
export ANTHROPIC_API_KEY="sk-your-api-key"
export ANTHROPIC_MODEL="your-model"

claude

07 / Help

Troubleshooting

If a request fails, check the status code, the model name, and the key permissions first.

401

Authentication failed

The key is missing or invalid. Check the Authorization header or create a replacement key.

403

Permission denied

Your key is valid, but your account or key cannot use this model or route.

404

Endpoint not found

Check the service address and endpoint path, and make sure the address does not include the docs page.

429

Rate limit or insufficient balance

You have reached a rate limit or your available balance is insufficient. Check the console before retrying.

5xx

Upstream unavailable

The selected model or its service is unavailable. Check the model status and try again later.

08 / Security

Security

A small amount of key hygiene prevents most avoidable access problems.

Treat your API key like a password.

Do not place the key in browser code or public client applications.

If the key is exposed, revoke it in Console → API Keys and create a replacement.

Use separate keys for different applications so you can revoke one without interrupting the others.

Ready to test? Open the API key page, copy a model ID, and run the first example.

Open API Keys