Your first request

curl -sS https://54-151-42-83.sslip.io/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Introduce yourself in one sentence",
    "stream": false
  }'

Next steps

• Auth & endpoints — the base URL and request headers
• CC Switch — method one, configure through a GUI
• Manual configuration — method two, configure Codex or Claude Code directly
• API Reference — find endpoints by protocol and job type

API base URL

Request header

Endpoint overview

List available models

The Models & Pricing page and all three model-discovery endpoints below are public. They do not require a signed-in session, cookie, or API key. All three read the same ArgoLink catalog; only the public path and JSON protocol shape differ.

Recommended endpointGET /v1/models

This is the default discovery endpoint. It returns an OpenAI-compatible list in which each data item represents one available model.

curl -sS https://54-151-42-83.sslip.io/v1/models

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.6-sol",
      "object": "model",
      "created": 0,
      "owned_by": "openai"
    }
  ]
}

Compatibility pathGET /models

This is an exact alias of /v1/models. The response body, status, model ordering, ETag, and cache behavior are identical. New integrations should prefer /v1/models; use this path only when a client is fixed to /models.

Gemini shapeGET /v1beta/models

This endpoint returns a Gemini-compatible model resource list. The name value carries a models/ prefix, while baseModelId contains the raw model ID.

curl -sS https://54-151-42-83.sslip.io/v1beta/models

{
  "models": [
    {
      "name": "models/gpt-5.6-sol",
      "baseModelId": "gpt-5.6-sol",
      "version": "001",
      "displayName": "gpt-5.6-sol",
      "description": "..."
    }
  ]
}

Print model IDs only

# OpenAI-compatible shape
curl -sS https://54-151-42-83.sslip.io/v1/models | jq -r '.data[].id'

# Gemini shape; print raw IDs without the models/ prefix
curl -sS https://54-151-42-83.sslip.io/v1beta/models | jq -r '.models[].baseModelId'

Request bodies match each official protocol; complete runnable examples for the media APIs live in the chapters on the left.

Next steps

• Text API overview — all three accepted protocols
• CC Switch — the easiest way to connect a coding tool
• Manual configuration — configure Codex CLI / Desktop or Claude Code

Get the live model IDs

The public model catalog is the source of truth for availability, providers, and recommended endpoints. This command prints every current text model in provider order, without limiting discovery to any region.

curl -sS 'https://54-151-42-83.sslip.io/api/catalog/v1/models?category=chat&sort=provider&page_size=100' \
  | jq -r '.items[] | [.provider_id, .id, .endpoint] | @tsv'

Accepted downstream protocols

Reasoning effort and thinking controls

Provider parameters are not interchangeable. For exact control, prefer /v1/chat/completions and send the top-level reasoning_effort or thinking field shown below. “Effective behavior” includes the provider contract, ArgoLink's current gateway translation, and live request results.

curl -N https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Explain what an idempotent API operation is in two sentences"}],
    "reasoning_effort": "low",
    "stream": true
  }'

For models with native effort control, a Responses request uses reasoning.effort; the gateway converts it to Chat Completions reasoning_effort. DeepSeek accepts none/low/high/max in Responses, where none disables thinking. Kimi K2.6 and K2.7 use model-specific thinking controls rather than effort, so use the Chat Completions shapes above.

OpenAI ResponsesPOST /v1/responses

curl -sS https://54-151-42-83.sslip.io/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro-0813",
    "input": "Explain what an idempotent API operation is in two sentences"
  }'

OpenAI Chat CompletionsPOST /v1/chat/completions

curl -sS https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [
      {"role": "user", "content": "Explain what an idempotent API operation is in two sentences"}
    ]
  }'

Anthropic MessagesPOST /v1/messages

curl -sS https://54-151-42-83.sslip.io/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.7-code",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Explain what an idempotent API operation is in two sentences"}
    ]
  }'

Vision input

Use deepseek-v4-flash-vision-exp for image understanding. Replace the example URL with a publicly reachable image URL.

curl -sS https://54-151-42-83.sslip.io/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "input": [{
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Describe this image briefly"},
        {"type": "input_image", "image_url": "https://your-public-image.example/image.jpg"}
      ]
    }]
  }'

Availability and pricing

Use the live Models & Pricing page for per-model input, output, cached-input, and cache-write prices. It also carries time-sensitive notes such as DeepSeek weekday peak pricing and the GLM Flash promotional period; do not treat request examples as a price quote.

Next steps

• Responses — Codex and unified text calls
• Chat Completions — OpenAI-compatible clients
• Claude Messages — Claude Code and Anthropic SDKs
• Models & Pricing — live availability and effective prices

Request fields

Minimal request

curl -sS https://54-151-42-83.sslip.io/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Confirm this connection in one sentence"
  }'

Read the response

The main non-streaming result is in output[]; text blocks use type=output_text, and token accounting is in usage. Do not hard-code one array index because tool calls and reasoning items can also appear in output[].

Request fields

Example request

curl -sS https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro-0813",
    "messages": [{"role":"user","content":"Confirm this connection in one sentence"}],
    "stream": false
  }'

Response and streaming

Non-streaming text is normally in choices[0].message.content, the termination reason in choices[0].finish_reason, and accounting in usage. With stream: true, accumulate text and tool calls from each SSE chunk's choices[].delta.

Request fields

Example request

curl -sS https://54-151-42-83.sslip.io/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.7-code",
    "max_tokens": 256,
    "messages": [{"role":"user","content":"Confirm this connection in one sentence"}]
  }'

Response and events

Non-streaming content is in content[]; text blocks use type=text and tool calls use type=tool_use. The stop reason is in stop_reason and accounting is in usage. A stream emits message_start, content-block events, message_delta, and message_stop.

Shared contract

Choose the matching guide

• GPT Image — generation, 1–16 reference images, and aspect-ratio behavior
• Nano Banana — three Google image models, aspect ratios, and output formats
• Grok Image — xAI generation, resolution, and up to 3 JSON reference images

Job lifecycle

1. 1Send model, prompt, and supported duration, aspect-ratio, resolution, or reference-image fields to POST /v1/videos/generations.
2. 2Save request_id from the response. It is the only identifier for subsequent status and content calls.
3. 3Wait while status is pending, download after done, and inspect the full error after failed or expired.

Model job examples

• Grok Video 1.5 — text-to-video, first-frame input, status polling, and MP4 download
• Seedance 2.0 / 2.5 — first/last frame, multi-image, video and audio references, direct media upload
• Gemini Omni — Google video jobs and reference-image parameters
• Infinite Canvas — submit video jobs through a client without writing code

Thinking controls

Top-level thinking.type accepts enabled or disabled. reasoning_effort accepts low, medium, high, xhigh, or max. Effective mapping is low→low, medium/high/xhigh→high, and max→max; omitted controls default to thinking enabled at high.

Example

curl -sS https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro-0813",
    "messages": [{"role": "user", "content": "Explain an idempotent API in two sentences"}],
    "reasoning_effort": "low"
  }'

See live input, output, cache, and weekday peak prices on Models & Pricing.

Thinking controls

The thinking toggle and effort mapping match V4 Pro. Live upstream tests verified the toggle and both low and max effort. This is an experimental model, so callers should tolerate version and latency changes.

Vision example

curl -sS https://54-151-42-83.sslip.io/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "input": [{"role": "user", "content": [
      {"type": "input_text", "text": "Describe this image briefly"},
      {"type": "input_image", "image_url": "https://example.com/image.jpg"}
    ]}],
    "reasoning": {"effort": "low"}
  }'

This model also uses weekday peak pricing. See Models & Pricing.

Thinking control

Send top-level thinking: {"type":"enabled"} or thinking: {"type":"disabled"}. Do not send reasoning_effort.

Example

curl -sS https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"glm-5.1","messages":[{"role":"user","content":"Explain one database transaction"}],"thinking":{"type":"enabled"}}'

See the live price on Models & Pricing.

Thinking control

When enabled, effort accepts low, medium, high, xhigh, and max. Effective mapping is low/medium/high→high and xhigh/max→max. To disable reasoning, send both thinking.type=disabled and reasoning_effort=none; none alone may still reason.

Disable-thinking example

curl -sS https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"glm-5.2","messages":[{"role":"user","content":"Reply only with OK"}],"thinking":{"type":"disabled"},"reasoning_effort":"none"}'

See the live price on Models & Pricing.

Reasoning effort

Accepts low, high, and max. The current gateway maps both low and high to upstream high, while max stays max. The only effective levels today are high and max; thinking cannot be disabled.

Example

curl -sS https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"glm-5.3","messages":[{"role":"user","content":"Compare optimistic and pessimistic locking"}],"reasoning_effort":"max"}'

See the live price on Models & Pricing.

Reasoning effort

Accepts low, high, and max; the effective levels today are high and max. Thinking cannot be disabled. Pricing may be promotional, so never infer a quote from this request example.

Example

curl -sS https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"glm-5.3-flash","messages":[{"role":"user","content":"Write a paginated SQL query"}],"reasoning_effort":"high"}'

See promotion status and live price on Models & Pricing.

Thinking control

Send thinking.type as enabled or disabled; do not send reasoning_effort. The current upstream reports the response model as auto when thinking is disabled, so keep it enabled if exact response-model identity matters.

Example

curl -sS https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"kimi-k2.6","messages":[{"role":"user","content":"Explain event sourcing"}],"thinking":{"type":"enabled"}}'

See the live price on Models & Pricing.

Thinking control

reasoning_effort is unsupported and thinking cannot be disabled. Do not send thinking.type=disabled: the compatibility layer may still return HTTP 200 but report model auto, violating a fixed-model contract.

Example

curl -sS https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"kimi-k2.7-code","messages":[{"role":"user","content":"Refactor this Go function and explain edge cases"}],"thinking":{"type":"enabled","keep":"all"}}'

See the live price on Models & Pricing.

Reasoning effort and latency

Accepts low, high, and max, preserved upstream. Do not send thinking; live tests show disabled is ignored. Changing effort mid-conversation invalidates Kimi prefix-cache hits, so choose one level on the first turn. K3 at max is inherently slow; low plus streaming reduces time to first token, while total latency still depends on upstream queueing and output length.

Lower-latency example

curl -N https://54-151-42-83.sslip.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"kimi-k3","messages":[{"role":"user","content":"Explain an idempotent API in two sentences"}],"reasoning_effort":"low","stream":true}'

See the live price on Models & Pricing.

Setup steps

1. 1Open CC Switch and add a custom provider.
2. 2Choose Codex or Claude and enter the matching base URL below.
3. 3Enter your ArgoLink key, then enable the provider.
4. 4If the target app is already running, restart it.

Configuration

Next steps

• Manual configuration — edit client configuration without CC Switch
• API Reference — see how protocols map to models

Choose your client

Verify the setup

1. 1Open Models & Pricing and confirm that the configured model ID is still in the live catalog.
2. 2Restart the client and send a minimal request that asks for a one-sentence response.
3. 3A 401 means the key needs attention. A model-unavailable error means you should choose a current model in the same category, not change the Base URL.

Shared config

Config file~/.codex/config.toml

model = "gpt-5.6-sol"
model_provider = "luckyapi"

[model_providers.luckyapi]
name = "ArgoLink"
base_url = "https://54-151-42-83.sslip.io/v1"
wire_api = "responses"
requires_openai_auth = false
experimental_bearer_token = "YOUR_API_KEY"

Next steps

• Claude Code — configure the other coding tool
• GPT Image — call the media APIs directly

Config file ~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://54-151-42-83.sslip.io",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY"
  }
}

Next steps

• Codex CLI / Desktop — the shared user-level config
• Cherry Studio — configure desktop chat and image generation

Before you start

1. 1Create and sign in to your ArgoLink account, then open the console.
2. 2Create a key on the API Keys page, copy it immediately, and store it safely. The full key is normally shown only once.
3. 3Make sure your wallet has available balance. Chat and image generation both consume credit.
4. 4Install the latest stable Cherry Studio release. Choose arm64.dmg on Apple Silicon Macs or setup.exe on Windows. Do not install a nightly build or run from source.

Add the ArgoLink provider

1. 1On first launch, choose “Configure other providers.” If you already skipped setup, open the lower-left gear and go to Settings → Model Providers.
2. 2Click “Add Provider” to open the custom-provider dialog.
3. 3Enter the values below, save, and enable the provider with the switch on its right.

Fill every endpoint field

Open “More settings / Add endpoint” and use the values below. All four OpenAI-compatible fields share the same Base URL; leave Gemini blank.

Fetch and add models

Click “Fetch model list.” Cherry Studio reads the public GET https://54-151-42-83.sslip.io/v1/models endpoint without an API key. In the returned list, click the “+” beside each model you want to add to this provider.

Test the connection and choose defaults

1. 1Click “Test” beside the API key and select only one currently available chat model. Do not choose “Test all models.”
2. 2A green “Passed” result confirms the URL, key, and network. Image models being marked “Skipped” is normal.
3. 3Open Settings → Default Models and choose one chat model and one image model from the live catalog.

Start chatting and generating images

Chat

1. 1Return to the main chat screen and find the ArgoLink group in the model selector.
2. 2Choose any chat model in that group, enter a message, and send it.

Image generation

1. 1Click “+” at the top of the main screen and open Drawing.
2. 2Choose ArgoLink as the provider, then select an image model whose endpoint type is “Image Generation (OpenAI).”
3. 3Enter a prompt and click Generate. Some models require the prompt itself to include 1:1, 16:9, or 9:16.

A sliced red apple on a dark wooden table, soft morning side light, shallow depth of field, 1:1 composition, no text, no watermark

Troubleshooting

Endpoints Cherry Studio calls

The authorization header is Authorization: Bearer <API Key>. Video submissions use POST /v1/videos/generations, but require a client with a video-job workflow.

Let local Codex help with installation

For assisted setup, give this page to a local Codex task and explicitly ask it to install the latest stable GitHub release, add the ArgoLink custom provider, fetch the live catalog, and test only one chat model. Provide your API key only inside a trusted local task that you control; never place the full key in public tasks, group chats, or screenshots.

Next steps

• Infinite Canvas — use chat, image, and video models
• GPT Image — image API parameters
• FAQ — troubleshoot common connection issues

Before you start

1. 1Create and sign in to your ArgoLink account, then make sure the wallet has available balance.
2. 2Create an API key in the console, copy it, and store it safely.
3. 3Open the model provider settings in Infinite Canvas and add a custom provider.

Provider configuration

Sync and select models

Save the provider, then refresh its model list. ArgoLink's public model discovery endpoint does not require an API key. If the client still shows a stale list, reload the provider first; manually entering a model ID is only a fallback for a stale client cache.

Use models on the canvas

1. 1Create the matching text, image, or video node and select the ArgoLink provider.
2. 2Select a model and enter the prompt. For reference-image editing, connect the image to a model node that supports edits.
3. 3Submit the task and wait for the result. Image and video generation usually take longer than text requests.

Related endpoints

Next steps

• GPT Image — image request parameters
• Nano Banana — the three image models and their parameters
• Grok Video 1.5 — the asynchronous video workflow
• FAQ — connection and timeout troubleshooting

Text to image (JSON)

curl -sS --max-time 600 \
  https://54-151-42-83.sslip.io/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A red apple on a wooden table, square 1:1 composition",
    "quality": "auto",
    "n": 1,
    "response_format": "b64_json"
  }' \
  -o image-response.json

Resolution and aspect ratio

Put the actual pixel dimensions in size and spell out the desired aspect ratio in the prompt. Billing uses the returned image's longest edge: up to 1024 is 1K, 1025–2048 is 2K, and above 2048 is 4K. 2K and 4K image generation may take longer; wait for the request to complete. Use these billing-conformant examples:

{
  "model": "gpt-image-2",
  "prompt": "A cinematic landscape, 16:9 composition",
  "size": "3840x2160",
  "quality": "auto",
  "n": 1,
  "response_format": "url"
}

Reference-image edit (JSON or multipart, 1–16 images)

Use JSON when your references are public HTTPS URLs or data URLs. Use multipart when the files are local. Choose one request-body format per request.

curl -sS --max-time 600 \
  https://54-151-42-83.sslip.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Combine the references into one cyberpunk scene, keep the subjects and use a square 1:1 composition" \
  -F "image[]=@./reference-1.png" \
  -F "image[]=@./reference-2.png" \
  -F "image[]=@./reference-3.png" \
  -F "quality=auto" \
  -F "n=1" \
  -F "response_format=b64_json" \
  -o image-edit-response.json

curl -sS --max-time 600 \
  https://54-151-42-83.sslip.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "images": [
      {"image_url": "https://example.com/reference-1.png"},
      {"image_url": "https://example.com/reference-2.png"}
    ],
    "prompt": "Keep the subjects and change the background",
    "size": "1024x1024",
    "quality": "auto",
    "n": 1,
    "response_format": "b64_json"
  }' \
  -o image-edit-json-response.json

Next steps

• Nano Banana — Google image generation and reference edits
• Grok Video 1.5 — async video generation

Choose a model

Text to image (JSON)

curl -sS --max-time 600 \
  https://54-151-42-83.sslip.io/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A cinematic product photo of a green glass bottle on stone",
    "aspect_ratio": "4:3",
    "n": 1,
    "output_format": "jpeg"
  }' \
  -o nano-banana-response.json

Single-reference edit (multipart)

curl -sS --max-time 600 \
  https://54-151-42-83.sslip.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=nano-banana-2" \
  -F "prompt=Keep the subject and replace the background with a quiet Japanese garden" \
  -F "image[]=@./reference.png" \
  -F "aspect_ratio=4:3" \
  -F "n=1" \
  -F "output_format=jpeg" \
  -o nano-banana-edit-response.json

Save the returned image

jq -r '.data[0].b64_json' nano-banana-response.json \
  | base64 --decode > nano-banana.jpg

Next steps

• Grok Image — xAI text-to-image and reference edits
• Infinite Canvas setup guide — configure the provider and models in the client

Text to image (JSON)

curl -sS --fail-with-body --max-time 600 \
  https://54-151-42-83.sslip.io/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A cinematic spacecraft leaving a Martian canyon",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1,
    "response_format": "url"
  }' \
  -o grok-image-response.json

Inspect the response and download the first image

RESPONSE=grok-image-response.json

jq . "$RESPONSE"
URL=$(jq -er '.data[0].url' "$RESPONSE") || exit 1
curl -fL "$URL" -o grok-image.png

Reference-image edit (JSON, up to 3 images)

curl -sS --fail-with-body --max-time 600 \
  https://54-151-42-83.sslip.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Combine the subjects into one cinematic cyberpunk scene",
    "images": [
      {"type": "image_url", "image_url": {"url": "https://example.com/reference-1.png"}},
      {"type": "image_url", "image_url": {"url": "https://example.com/reference-2.png"}},
      {"type": "image_url", "image_url": {"url": "https://example.com/reference-3.png"}}
    ],
    "aspect_ratio": "4:3",
    "resolution": "2k",
    "n": 1,
    "response_format": "b64_json"
  }' \
  -o grok-image-edit-response.json

Reference-image edit (multipart, one local image)

curl -sS --fail-with-body --max-time 600 \
  https://54-151-42-83.sslip.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=grok-imagine-image-2.0" \
  -F "prompt=Combine the subject into one cinematic cyberpunk scene" \
  -F "image=@./reference-1.png" \
  -o grok-image-edit-response.json

Next steps

• Grok Video 1.5 — async video generation
• Gemini Omni — Google video generation

Billed by output second

Charges use the resolution and output seconds of a successfully generated video. First-frame and reference images currently have no separate image surcharge; failed or expired jobs incur no video charge. The live catalog remains the final price source.

Step 1: submit a text-to-video job

API_KEY="YOUR_API_KEY"
BASE="https://54-151-42-83.sslip.io"

ID=$(curl -fsS "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "A cinematic spacecraft leaving a Martian canyon",
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' \
  | jq -er '.request_id') || exit 1

printf 'Request ID: %s\n' "$ID"

Step 2: poll the job status

curl -fsS "$BASE/v1/videos/$ID" \
  -H "Authorization: Bearer $API_KEY" | jq .

Step 3: wait automatically and download the MP4

curl -fSL --retry 120 --retry-delay 5 --retry-all-errors \
  "$BASE/v1/videos/$ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o grok-video.mp4

Image to video (1 local first-frame image)

base64 < ./reference.png | tr -d '\n' | \
jq -Rs '{
  model: "grok-imagine-video-1.5",
  prompt: "Animate this still image with a slow cinematic camera move",
  image: {url: ("data:image/png;base64," + .)},
  duration: 10,
  resolution: "720p"
}' > grok-video-request.json

curl -sS --fail-with-body \
  https://54-151-42-83.sslip.io/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @grok-video-request.json | jq .

image accepts one public HTTPS URL, base64 data URI or file_id, and uses it as the first frame. Once you have the request_id, reuse the status and content endpoints above.

Multi-reference video (JSON, 1–7 images)

curl -sS --fail-with-body \
  https://54-151-42-83.sslip.io/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "Use the person from <IMAGE_0> and the clothing from <IMAGE_1>",
    "reference_images": [
      {"url": "https://example.com/person.png"},
      {"url": "https://example.com/clothing.png"}
    ],
    "duration": 10,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' | jq .

Next steps

• Gemini Omni — Google video generation
• FAQ — troubleshoot request issues

Models

Output is a 24 fps H.264 MP4 with a model-generated AAC stereo audio track (44.1 kHz) that cannot currently be turned off. Every request produces exactly one video (n must be 1 or omitted). At 720p, 16:9 renders 1280×720 and 1:1 renders 960×960. Generation usually takes a few minutes and longer when the queue is busy, so always poll instead of assuming a deadline. Seedance 2.0, 2.0 Mini and 2.0 Fast do not support real human faces: a first frame or reference image showing a real person's face may fail to generate.

Billed by output second

Price = per-second rate for the model and resolution × billed seconds: the seconds of the delivered video (its real length rounded to whole seconds) plus the seconds of any reference videos (their lengths added up, with any part of a second left off). "Official" is the BytePlus ModelArk list price for a 16:9 clip without video input, converted to a per-second amount; ArgoLink charges 75% of it, rounded to two significant figures. The input mode (text, first frame, first + last frame, reference images or audio) does not change the rate, and uploads are free. Reference videos are billed at the same per-second rate as the output; reference images and audio are free. Failed or expired jobs are not charged. If duration is omitted the job runs and bills as 5 seconds. Examples: a 10-second 720p seedance-2.0 clip costs $1.10; a 4-second 720p seedance-2.0-mini clip costs $0.228; a 5-second 720p seedance-2.0 clip with a 3-second reference video bills 8 seconds, $0.88. The live catalog on the model pages remains the final price source.

Request fields

Field names from other video APIs

Requests written for fal or OpenRouter can be sent as they are: every name in the right column means the field on its left. Give each input one name. Two names for the same input with different values, or frame_images / input_references together with the fields they stand for, are rejected with 400.

{
  "model": "seedance-2.5",
  "prompt": "The person in image 1 walks into the scene in video 1",
  "size": "1280x720",
  "duration": 5,
  "input_references": [
    {"type": "image_url", "image_url": {"url": "https://example.com/person.png"}},
    {"type": "video_url", "video_url": {"url": "https://example.com/scene.mp4"}}
  ]
}

Inside input_references, images, videos and audio are numbered separately in the order they appear: the first image_url item is image 1 and the first video_url item is video 1.

Input modes

The mode is derived from which media fields are present — there is no mode parameter:

start_image/end_image and the three reference lists are mutually exclusive. Asset counts above the model's limit, @ mentions past the end of an array, and resolutions or durations outside the model's range are rejected with 400 at submission, before generation starts.

Reference limits

The three kinds of reference combine freely within the model's per-kind and total caps.

On the 2.0 family, 9 images + 3 videos or 9 images + 3 audio clips fit, but 9 images + 3 videos + 3 audio clips is 15 assets, over the total, and is rejected with 400.

Asset counts and media types are checked when you submit. Reference video and audio lengths are checked after upload, before generation starts: a clip out of range fails the job with invalid_input and nothing is charged. Assets outside the size or format ranges can make the job fail.

Step 0: upload local files (only when you have them)

Ask for an upload ticket, PUT the bytes directly to the returned storage URL, then use media_url in the generation request. Sub2API never proxies file bytes, so large videos do not hit the 1 MiB JSON limit.

API_KEY="YOUR_API_KEY"
BASE="https://54-151-42-83.sslip.io"
FILE=./first-frame.jpg

TICKET=$(curl -fsS "$BASE/v1/media/uploads" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"seedance-2.5\",\"type\":\"image\",\"content_type\":\"image/jpeg\",\"size_bytes\":$(stat -f%z "$FILE")}")

curl -fsS -X PUT "$(jq -r .upload_url <<<"$TICKET")" \
  -H "Content-Type: image/jpeg" --data-binary @"$FILE"

MEDIA_URL=$(jq -r .media_url <<<"$TICKET")

The ticket returns upload_url (valid 15 minutes, PUT with exactly the declared Content-Type), media_url (readable for 7 days) and the matching upload_expires_at / expires_at timestamps. size_bytes must equal the real file size. Tickets are free and do not create a job. On Linux use stat -c%s.

Step 1: submit a text-to-video job

ID=$(curl -fsS "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A golden retriever runs along a sunlit beach, slow-motion, camera tracking sideways, cinematic",
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' \
  | jq -er '.request_id') || exit 1

printf 'Request ID: %s\n' "$ID"

A successful submission returns HTTP 202 with {"request_id": "…"}. Keep it — it is the only handle for status, download and billing records.

Step 2: poll the job status

curl -fsS "$BASE/v1/videos/$ID" \
  -H "Authorization: Bearer $API_KEY" | jq .

{
  "request_id": "e9a36267-5a81-46ee-87a1-baf62bec7e9a",
  "status": "pending",
  "model": "seedance-2.5",
  "created_at": 1789379975,
  "progress": 37,
  "estimated_seconds_remaining": 128
}

{
  "created_at": 1789379975,
  "model": "seedance-2.5",
  "progress": 100,
  "request_id": "e9a36267-5a81-46ee-87a1-baf62bec7e9a",
  "status": "done",
  "usage": { "billed_seconds": 8, "output_seconds": 8, "reference_video_seconds": 0 },
  "video": { "duration": 8, "url": "https://54-151-42-83.sslip.io/v1/videos/e9a36267-5a81-46ee-87a1-baf62bec7e9a/content" }
}

Poll every 10–15 seconds. pending means still generating: progress (0–99) estimates how far the job has come and estimated_seconds_remaining how many seconds are left, both worked out from the forecast of the job's queue and generation time. Until that forecast exists progress is 0 and there is no estimated_seconds_remaining; a job that runs past its forecast stays at 99 until it finishes. created_at is the submission time in Unix seconds. done means the MP4 is ready: progress is 100 and video.url is the full download address, the content endpoint from Step 3, requested with the same key; usage gives the output seconds, the reference video seconds and their sum, billed_seconds; failed or expired means nothing was produced and nothing is charged. On failed the error object gives the reason and whether a plain retry can succeed; see Job failures below. A job that finds no capacity within 10 minutes ends with capacity_unavailable; once generation has started the job waits for its result, and ends with generation_timeout only if it is still unfinished after 24 hours. Billing happens once, when done is first observed, using usage.billed_seconds.

Step 3: wait automatically and download the MP4

curl -fSL --retry 120 --retry-delay 5 --retry-all-errors \
  "$BASE/v1/videos/$ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o seedance.mp4

The content endpoint streams the finished MP4 (video/mp4, Range supported) and returns an error status while the job is still pending, so the retry loop above waits up to about 10 minutes without saving an error body as a video.

First frame (seedance-2.0-mini, 5 seconds, 720p)

curl -fsS "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini",
    "prompt": "The logo floats in space; a green lightning bolt strikes it, sparks burst, camera pushes in slowly",
    "start_image": {"url": "'"$MEDIA_URL"'"},
    "duration": 5,
    "resolution": "720p"
  }' | jq .

The video takes its ratio from the first frame, so no aspect_ratio is needed: a square frame renders at 960×960. This exact request bills 5 × $0.057 = $0.285.

First + last frame (seedance-2.0, 4K)

curl -fsS "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "Day turns into night over the same skyline, clouds roll by, lights come on",
    "start_image": {"url": "https://example.com/day.jpg"},
    "end_image": {"url": "https://example.com/night.jpg"},
    "duration": 6,
    "resolution": "4k"
  }' | jq .

Both frames must land on one aspect ratio, which the video uses too; a mismatched pair fails with invalid_input on end_image and nothing is charged. This 6-second 4K request bills 6 × $0.58 = $3.48.

Multimodal reference: image + video + audio (seedance-2.5)

curl -fsS "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "The woman in @Image 1 speaks warmly to the camera in time with @Audio 1, moving the way @Video 1 does, natural lip movement, soft studio light",
    "reference_images": [{"url": "https://example.com/portrait.jpg"}],
    "reference_videos": [{"url": "https://example.com/motion.mp4"}],
    "reference_audios": [{"url": "https://example.com/voice.mp3"}],
    "duration": 4,
    "aspect_ratio": "9:16",
    "resolution": "720p"
  }' | jq .

Errors

Errors on submit, status and download come back as an HTTP status with the body {"error": {"type": "…", "code": "…", "param": "…", "message": "…"}}: message is a reason you can show, param names the request field at fault, and code is stable.

Job failures

A submitted job can still fail while it generates. Its status then reads "status": "failed" with an error object: code is a stable failure code, message gives the exact reason, retryable is true when the failure consumed no generation and submitting the same request again is safe, and false when the same request cannot succeed or the outcome could not be confirmed; input problems also carry field. Failed jobs are not charged.

{
  "request_id": "639e6b9e-26eb-43a6-917a-958adcf4bca2",
  "status": "failed",
  "model": "seedance-2.0-mini",
  "error": {
    "code": "invalid_input",
    "message": "start_image is 1920x1080, which renders at 16:9, but end_image is 1024x1024, which renders at 1:1. Both frames must render at the same aspect ratio.",
    "retryable": false,
    "field": "end_image"
  }
}

Next steps

• Videos — the shared asynchronous job contract
• Grok Video 1.5 — xAI video generation
• FAQ — troubleshoot request issues

Step 1: submit a text-to-video job

API_KEY="YOUR_API_KEY"
BASE="https://54-151-42-83.sslip.io"

ID=$(curl -fsS "$BASE/v1/videos/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-1.1",
    "prompt": "A cinematic sunrise over the ocean with a slow camera push",
    "duration": 8,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }' \
  | jq -er '.request_id') || exit 1

printf 'Request ID: %s\n' "$ID"

Step 2: poll the job status

curl -fsS "$BASE/v1/videos/$ID" \
  -H "Authorization: Bearer $API_KEY" | jq .

Step 3: wait automatically and download the MP4

curl -fSL --retry 120 --retry-delay 5 --retry-all-errors \
  "$BASE/v1/videos/$ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  -o gemini-omni.mp4

Image to video (1 local first-frame image)

curl -sS --fail-with-body \
  https://54-151-42-83.sslip.io/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gemini-omni-1.1" \
  -F "prompt=Animate this first frame with a slow cinematic camera move" \
  -F "duration=8" \
  -F "aspect_ratio=16:9" \
  -F "resolution=720p" \
  -F "image=@./first-frame.jpg;type=image/jpeg" | jq .

image accepts exactly one local PNG or JPEG and locks it as the first frame. Once you have the request_id, reuse the status and content endpoints above.

Multi-reference video (multipart, 1–5 images)

curl -sS --fail-with-body \
  https://54-151-42-83.sslip.io/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gemini-omni-1.1" \
  -F "prompt=Use the person and wardrobe from the reference images" \
  -F "duration=8" \
  -F "aspect_ratio=9:16" \
  -F "resolution=720p" \
  -F "reference_images=@./person.png;type=image/png" \
  -F "reference_images=@./wardrobe.jpg;type=image/jpeg" | jq .

Next steps

• FAQ — troubleshoot request issues
• Quickstart — review the onboarding flow

Next steps

• Quickstart — review the onboarding flow
• Auth & endpoints — verify the base URL and headers