API Reference

Base URL: https://api.framefly.com.cn

Introduction

Framefly is a unified AI API platform. One API key, access to the best AI models for text, image, and video generation. All APIs follow OpenAI-compatible conventions, so you can use the official OpenAI SDK with minimal changes.

Base URL

https://api.framefly.com.cn

OpenAI SDK Compatible

You can use the official OpenAI Python or Node.js SDK — just change base_url to https://api.framefly.com.cn/v1 and set your Framefly API key. No other code changes needed for chat completions.

Authentication

All API requests require a Bearer token in the Authorization header. Your API key starts with ff_live_.

Request Header

Authorization: Bearer ff_live_xxxxxxxxxxxxxxxxxxxxxxxx

Create and manage your API keys in the Console under API Keys. Keys are shown only once on creation — store them securely.

Keep your keys secret

Never expose API keys in client-side code, public repositories, or logs. Use environment variables or a secrets manager.

POST/v1/chat/completions

LLM Chat

OpenAI-compatible chat completions endpoint. Supports all major language models including GPT-4o, Claude 3.5 Sonnet, Gemini, and more. Pass any parameters the underlying model accepts — they are forwarded transparently.

Parameters

Name	Type	Required	Description
`model`	string	required	Model ID (e.g. gpt-4o, claude-3-5-sonnet-20241022)
`messages`	array	required	Array of message objects with role and content
`stream`	boolean	optional	If true, response is streamed as Server-Sent Events. Default: false
`temperature`	number	optional	Sampling temperature 0–2. Higher = more random. Default: 1
`max_tokens`	integer	optional	Maximum tokens to generate
`top_p`	number	optional	Nucleus sampling probability. Default: 1

Code Examples

curl https://api.framefly.com.cn/v1/chat/completions \
  --header "Authorization: Bearer ff_live_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Hello, world!"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Response

Success

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712966400,
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21
  }
}

Error

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your account balance is too low to complete this request.",
    "request_id": "req_abc123"
  }
}

Streaming

Set stream: true to receive a Server-Sent Events (SSE) stream. Each event is a JSON chunk prefixed with data: . The stream ends with data: [DONE].

curl https://api.framefly.com.cn/v1/chat/completions \
  --header "Authorization: Bearer ff_live_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

Stream Chunk

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"}}]}

data: [DONE]

POST/v1/images/generations

Image Generation

Synchronous image generation. Returns an OpenAI-compatible response immediately when the image is ready. Parameters are forwarded transparently to the upstream model — refer to each model's documentation for supported options.

Parameters

Name	Type	Required	Description
`model`	string	required	Model ID (e.g. seedream-4.0, flux-1.1-pro)
`prompt`	string	required	Text description of the image to generate
`size`	string	optional	Image dimensions, e.g. "1024x1024". Model-dependent.
`n`	integer	optional	Number of images to generate. Default: 1
`quality`	string	optional	Image quality, e.g. "standard" or "hd". Model-dependent.
`style`	string	optional	Image style, e.g. "vivid" or "natural". Model-dependent.

Code Examples

curl https://api.framefly.com.cn/v1/images/generations \
  --header "Authorization: Bearer ff_live_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-4.0",
    "prompt": "A futuristic city at sunset, cinematic lighting",
    "size": "1024x1024",
    "n": 1
  }'

Response

Success

{
  "created": 1712966400,
  "data": [
    {
      "url": "https://cdn.framefly.ai/images/abc123.png"
    }
  ]
}

Video Generation

Video generation is asynchronous. Create a task, then poll for status until it completes. Recommended polling interval: every 3–5 seconds.

POST/v1/videos/generations

1. Create Task

Submit a video generation task. Returns a task object with an id to track progress. Supports two request formats: a flat prompt string or a content[] array (Volcengine-style).

Name	Type	Required	Description
`model`	string	required	Video model ID (e.g. seedance-1.0-lite, kling-v3)
`content`	array	optional	Array of content objects [{type, text}] (Volcengine-style)
`prompt`	string	optional	Flat text prompt (alternative to content[])
`duration`	integer	optional	Video duration in seconds. Default: 5
`resolution`	string	optional	e.g. "720p" or "1080p". Model-dependent.
`ratio`	string	optional	Aspect ratio, e.g. "16:9", "9:16", "1:1"
`seed`	integer	optional	Random seed for reproducible results
`generate_audio`	boolean	optional	Generate audio track. Default: false
`watermark`	boolean	optional	Add watermark. Default: false
`camera_fixed`	boolean	optional	Lock camera position. Default: false

curl https://api.framefly.com.cn/v1/videos/generations \
  --header "Authorization: Bearer ff_live_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedance-1.0-lite",
    "prompt": "A red panda playing in a bamboo forest",
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p"
  }'

Response

{
  "id": "task_abc123xyz",
  "model": "seedance-1.0-lite",
  "status": "queued",
  "created_at": 1712966400
}

GET/v1/videos/generations/:id

2. Get Task

Poll this endpoint to check task progress. The status field progresses through: queued → running → succeeded or failed.

# Poll until status is succeeded or failed
curl https://api.framefly.com.cn/v1/videos/generations/task_abc123xyz \
  --header "Authorization: Bearer ff_live_xxx"

Response (succeeded)

{
  "id": "task_abc123xyz",
  "model": "seedance-1.0-lite",
  "status": "succeeded",
  "created_at": 1712966400,
  "content": {
    "video_url": "https://cdn.framefly.ai/videos/abc123.mp4"
  },
  "usage": {
    "total_tokens": 150
  }
}

GET/v1/videos/generations

Paginated list of video generation tasks for the authenticated account.

Name	Type	Required	Description
`page_num`	integer	optional	Page number. Default: 1
`page_size`	integer	optional	Items per page. Default: 20, max: 100
`filter.status`	string	optional	Filter by status: queued, running, succeeded, failed
`filter.model`	string	optional	Filter by model ID
`filter.task_ids`	string	optional	Comma-separated task IDs to filter by

Response

{
  "data": [
    { "id": "task_abc123xyz", "model": "seedance-1.0-lite", "status": "succeeded", "created_at": 1712966400 }
  ],
  "total": 42,
  "page_num": 1,
  "page_size": 20
}

DELETE/v1/videos/generations/:id

4. Delete Task

Status	Result
`queued`	Task is cancelled
`running`	Cannot delete — returns 409 error
`succeeded`	Task and assets are deleted
`failed`	Task record is deleted

GET/v1/models

Models

Returns the list of all available models across text, image, and video categories. This endpoint is public — no authentication required.

Response

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "owned_by": "openai",
      "category": "chat"
    },
    {
      "id": "seedream-4.0",
      "object": "model",
      "owned_by": "bytedance",
      "category": "image"
    },
    {
      "id": "seedance-1.0-lite",
      "object": "model",
      "owned_by": "bytedance",
      "category": "video"
    }
  ]
}

GET/v1/account/balance

Account

Retrieve the current balance and tier information for the authenticated account.

Response

{
  "balance": 12.50,
  "currency": "USD",
  "tier": "growth",
  "discount_pct": 5
}

Rate Limits

Framefly enforces two levels of rate limiting. When exceeded, the API returns a 429 status with a Retry-After header indicating when you may retry.

Scope	Limit	Applies To
IP	30 burst / 10 per second	All endpoints
Account	60 RPM (default)	Per API key

Account-level RPM is configured per API key via the rate_limit_rpm setting (default: 60). Contact support to increase limits for high-throughput workloads.

Error Handling

All errors follow a consistent JSON format. The request_id field uniquely identifies the request — include it when contacting support.

Error Response Format

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your account balance is too low to complete this request.",
    "request_id": "req_abc123def456"
  }
}

Common Error Codes

HTTP	Code	Description
401	`unauthorized`	Missing or invalid API key
402	`insufficient_balance`	Account balance is too low
404	`not_found`	Requested resource does not exist
422	`validation_error`	Request body failed validation
429	`rate_limited`	Too many requests — check Retry-After header
502	`upstream_error`	Upstream model provider returned an error

API Reference

Introduction

Authentication

LLM Chat

Parameters

Code Examples

Response

Streaming

Image Generation

Parameters

Code Examples

Response

Video Generation

1. Create Task

2. Get Task

3. List Tasks

4. Delete Task

Models

Account

Rate Limits

Error Handling

Common Error Codes