客户 API 接入文档

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: customer-order-20261027-000001

export FRAMEGATE_API_KEY='YOUR_API_KEY'
export FRAMEGATE_BASE_URL='https://api.myanimforge.com'

curl --fail-with-body "$FRAMEGATE_BASE_URL/v1/models" \
  -H "Authorization: Bearer $FRAMEGATE_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "YOUR_VIDEO_MODEL_ID",
      "kind": "video",
      "billing_unit": "seconds",
      "pricing_rules": [],
      "input_price": "0.00000000",
      "output_price": "0.15000000",
      "max_input": 32768,
      "max_output": 4096,
      "max_seconds": 30
    }
  ]
}

{
  "model": "REPLACE_WITH_AUTHORIZED_VIDU_Q3_TURBO_ID",
  "prompt": "参考主体 [@image1]，固定镜头，柔和自然光，光影缓慢移动，无文字。",
  "duration_seconds": 5,
  "media": [
    {
      "type": "image",
      "url": "https://your-public-assets.example/reference.jpg",
      "role": "reference_image"
    }
  ],
  "options": {
    "resolution": "540p",
    "aspect_ratio": "16:9",
    "audio": false,
    "bgm": false,
    "off_peak": false
  }
}

curl --fail-with-body "$FRAMEGATE_BASE_URL/v1/videos" \
  -H "Authorization: Bearer $FRAMEGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: customer-video-order-000001' \
  --data-binary @video-request.json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "model": "YOUR_VIDEO_MODEL_ID",
  "status": "queued",
  "usage": {
    "video_seconds": null,
    "video_count": null,
    "total_tokens": null,
    "input_tokens": null,
    "output_tokens": null
  },
  "billing": {
    "currency": "CNY",
    "amount": "0.00000000",
    "status": "reserved",
    "reserved_amount": "0.75000000"
  },
  "result": {
    "url": null,
    "urls": []
  },
  "error_code": null
}

curl --fail-with-body "$FRAMEGATE_BASE_URL/v1/videos/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer $FRAMEGATE_API_KEY"

{
  "id": "11111111-1111-4111-8111-111111111111",
  "model": "YOUR_VIDEO_MODEL_ID",
  "status": "succeeded",
  "usage": {
    "video_seconds": "5.0000",
    "video_count": 1,
    "total_tokens": 0,
    "input_tokens": 0,
    "output_tokens": 0
  },
  "billing": {
    "currency": "CNY",
    "amount": "0.75000000",
    "status": "settled",
    "reserved_amount": "0.75000000"
  },
  "result": {
    "url": "https://media.example/result.mp4",
    "urls": [
      "https://media.example/result.mp4"
    ]
  },
  "error_code": null
}

{
  "type": "image",
  "url": "https://your-public-assets.example/reference.jpg",
  "role": "reference_image"
}

curl --fail-with-body "$FRAMEGATE_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $FRAMEGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: customer-text-order-000001' \
  -d '{
    "model": "YOUR_TEXT_MODEL_ID",
    "messages": [{"role": "user", "content": "写一个五秒短视频的镜头脚本"}],
    "max_tokens": 512,
    "stream": false
  }'

{
  "gateway": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "billing": {
      "currency": "CNY",
      "amount": "0.00200000",
      "status": "settled",
      "reserved_amount": "0.02000000"
    }
  }
}

curl --fail-with-body "$FRAMEGATE_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $FRAMEGATE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: customer-image-order-000001' \
  -d '{"model":"YOUR_IMAGE_MODEL_ID","prompt":"白色桌面上的蓝色陶瓷杯，柔和自然光","n":1}'

{
  "id": "22222222-2222-4222-8222-222222222222",
  "model": "YOUR_IMAGE_MODEL_ID",
  "status": "succeeded",
  "data": [
    {
      "url": "https://media.example/result.png"
    }
  ],
  "usage": {
    "image_count": 1
  },
  "billing": {
    "currency": "CNY",
    "amount": "0.10000000",
    "status": "settled",
    "reserved_amount": "0.10000000"
  },
  "error_code": null
}

curl --fail-with-body "$FRAMEGATE_BASE_URL/v1/balance" \
  -H "Authorization: Bearer $FRAMEGATE_API_KEY"

{
  "balance": "100.00000000",
  "reserved": "2.00000000",
  "available": "98.00000000",
  "currency": "CNY"
}

curl --fail-with-body --get "$FRAMEGATE_BASE_URL/v1/usage" \
  -H "Authorization: Bearer $FRAMEGATE_API_KEY" \
  --data-urlencode 'start=2026-10-01T00:00:00+08:00' \
  --data-urlencode 'end=2026-11-01T00:00:00+08:00'

{
  "data": [
    {
      "model_id": "YOUR_VIDEO_MODEL_ID",
      "kind": "video",
      "calls": 2,
      "settled_calls": 1,
      "input_tokens": "0",
      "output_tokens": "0",
      "video_seconds": "5.0000",
      "image_count": 0,
      "amount": "0.75000000"
    }
  ],
  "currency": "CNY"
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "可用余额不足以预占本次调用额度",
    "request_id": "HTTP_TRACE_ID"
  }
}

python -m pip install requests
# Linux / macOS / Git Bash
export FRAMEGATE_API_KEY='YOUR_API_KEY'
python video_client.py --payload video-request.json --state order-000001.json

# Windows PowerShell
$env:FRAMEGATE_API_KEY = 'YOUR_API_KEY'
python video_client.py --payload video-request.json --state order-000001.json