Agent Quickstart (Registered Users)

0. Document Goal

This page is for automated Agent integration (for example OpenClaw), not for human onboarding flow. Prerequisite: the user is already registered and can provide a valid API Key.

Success criteria: the Agent completes one POST /v1/chat/completions call and receives HTTP 200, without switching guidance pages.

1. Automation Contract

base_url: https://tokenhub.link/v1
endpoint: POST /chat/completions
auth_header: Authorization: Bearer $TOKENHUB_API_KEY
content_type: application/json
required_field:
  - model
  - messages
supported_model_formats:
  - deepseek-v3.2
  - alibaba/deepseek-v3.2
  - tokenhub_plan_model_name
success_criteria:
  - http_status == 200
  - response.choices[0].message.content exists

2. Agent Checklist

[Step-1] Read TOKENHUB_API_KEY
[Step-2] If empty, ask the user to create a key in console and write it to environment variables
[Step-3] Send the minimal viable request (see Step-3 example)
[Step-4] Validate status code and key response fields
[Step-5] Write "integration complete" status (model, timestamp, result summary)

Note: API Key is shown only once when created in console. The Agent must not expose key plaintext in logs, chat, or error stacks.

3. Minimal Viable Request (Executable)

curl -sS "https://tokenhub.link/v1/chat/completions" \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [
      {"role": "user", "content": "Reply with OK only."}
    ],
    "max_tokens": 32,
    "temperature": 0
  }'

4. Response Validation (Machine Check)

assert(http_status == 200)
assert(response.object in ["chat.completion", "chat.completion.chunk"])
assert(len(response.choices) > 0)
assert(response.choices[0].message.content is not null)

If you need stable routing boundaries, combine user preference constraints (region / provider / model). See Routing Strategy.

5. Optional: Multimodal Quick Validation

When the Agent needs to validate image/video capability, run the minimal steps below. It is recommended to finish text-path validation first.

# [Image] Create generation task (synchronous response)
curl -sS "https://tokenhub.link/v1/images/generations" \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wanx2.1-t2i-turbo",
    "prompt": "A futuristic city skyline at sunrise",
    "size": "1024*1024"
  }'

# Image validation checks
assert(http_status == 200)
assert(response.data exists or response.output exists)

# Image download example (replace {image_url} with actual return value)
curl -L "{image_url}" -o output-image.png
assert(file_exists("output-image.png"))

# [Video] Submit task (asynchronous)
curl -sS "https://tokenhub.link/v1/video/generations" \
  -H "Authorization: Bearer $TOKENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.6-t2v",
    "prompt": "A robot walking in the rain, cinematic shot"
  }'

# [Video] Poll task result (replace {task_id} with submit response value)
curl -sS "https://tokenhub.link/v1/video/tasks/{task_id}?model=wan2.6-t2v" \
  -H "Authorization: Bearer $TOKENHUB_API_KEY"

# Video validation checks
assert(http_status == 200)
assert(task_status in ["PENDING", "RUNNING", "SUCCEEDED"])
if task_status == "SUCCEEDED":
  assert(video_url exists)

# Video download example (replace {video_url} with actual return value)
curl -L "{video_url}" -o output-video.mp4
assert(file_exists("output-video.mp4"))

After task success, download files immediately and transfer them into your object storage to avoid temporary-link expiration.

For full parameters and model lists, see Image Model Guide and Video Model Guide.

6. Error Handling Recommendations (Conclusion Only)

if status == 401:
  stop_and_request_new_key()

if status in [429, 500, 502, 503, 504]:
  retry_with_exponential_backoff(max_attempts=3)

if region_unavailable_or_no_supplier:
  switch_allowed_region_or_model_format()

if repeated_failure:
  escalate_to_contact_page(topic="enterprise")

Contact entry: Enterprise Support.

7. Completion Output Template (for Agent write-back)

{
  "integration_status": "success",
  "provider_mode": "platform-routing",
  "model": "deepseek-v3.2",
  "endpoint": "POST /v1/chat/completions",
  "validated_at": "ISO-8601",
  "notes": "TokenHub API is ready for production wiring."
}