Overview

One contract for multiple AI workflows

TokenMarket exposes a unified external API so teams can keep one authentication method, one base URL, and one response style while calling different model capabilities.

OpenAI-style JSON request and response formats

One API key for chat, responses, embeddings, images, audio, rerank, and video generation

Unified billing, quota checks, streaming events, and request tracing headers

Latest capability update

This page now reflects the latest public surface: chat/completions accepts multimodal text plus image_url content parts, /v1/responses accepts native Responses-style input_text and input_image content parts and supports both non-streaming JSON and SSE streaming, and the recommended public Base URL is https://cloud.hopegate.ai/api.

Authentication

Authentication and base URL

Every request uses a Bearer token. Use the official TokenMarket public base URL below.

Base URL

https://cloud.hopegate.ai/api

Required headers

Authorization: Bearer YOUR_TOKENMARKET_API_KEY
Content-Type: application/json

Create API keys from the TokenMarket console, then send them with the Authorization header.

Quick start

The fastest way to verify connectivity is to send a minimal chat request.

curl -X POST "https://cloud.hopegate.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_TOKENMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek-V4-pro",
    "messages": [
      { "role": "user", "content": "Reply with only OK." }
    ],
    "stream": false
  }'

Core endpoints

Supported unified endpoints

These endpoints are available through the current public API surface.

Path	Purpose	Notes
/v1/chat/completions	Chat completions and reasoning outputs	Supports standard OpenAI-style messages, including text plus image_url content parts.
/v1/responses	Responses-style unified response interface	Supports both non-streaming JSON results and SSE streaming events; when input is a message array, use native Responses content parts: input_text for text and input_image for images, rather than the chat endpoint's text and image_url parts.
/v1/embeddings	Text embeddings	Returns embedding vectors in the upstream response format.
/v1/images/generations	Text-to-image generation	Supports response_format, size, quality, and n when the upstream model allows them.
/v1/audio/speech	Text-to-speech generation	Returns binary audio with TokenMarket request and billing headers.
/v1/rerank	Document reranking	Availability depends on the upstream model enabled for your account.
/v1/video/generations	Video generation task creation	Usually returns an asynchronous task payload from the upstream service.

Language examples

Code examples

All samples use the same API key pattern. Replace only YOUR_TOKENMARKET_API_KEY before running them.

Chat completion

cURL

curl -X POST "https://cloud.hopegate.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_TOKENMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek-V4-pro",
    "messages": [
      { "role": "user", "content": "Reply with only OK." }
    ],
    "stream": false
  }'

Multimodal chat completion

cURL

curl -X POST "https://cloud.hopegate.ai/api/v1/chat/completions"   -H "Authorization: Bearer YOUR_TOKENMARKET_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Describe the image in one sentence." },
          {
            "type": "image_url",
            "image_url": { "url": "https://example.com/cat.png" }
          }
        ]
      }
    ],
    "stream": false
  }'

Responses API and streaming

cURL

curl -N -X POST "https://cloud.hopegate.ai/api/v1/responses"   -H "Authorization: Bearer YOUR_TOKENMARKET_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-5.4",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Describe this image in one sentence." },
          {
            "type": "input_image",
            "image_url": "https://example.com/cat.png"
          }
        ]
      }
    ],
    "stream": false
  }'

Responses API with a data URL image

cURL

curl -X POST "https://cloud.hopegate.ai/api/v1/responses"   -H "Authorization: Bearer YOUR_TOKENMARKET_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-5.4",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Describe this image in one short sentence." },
          {
            "type": "input_image",
            "image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+a9d0AAAAASUVORK5CYII="
          }
        ]
      }
    ],
    "stream": false
  }'

Embeddings

cURL

curl -X POST "https://cloud.hopegate.ai/api/v1/embeddings" \
  -H "Authorization: Bearer YOUR_TOKENMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-large",
    "provider": "dataeyes",
    "input": "TokenMarket unified API integration"
  }'

Image generation

cURL

curl -X POST "https://cloud.hopegate.ai/api/v1/images/generations" \
  -H "Authorization: Bearer YOUR_TOKENMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "provider": "dataeyes",
    "prompt": "A minimal geometric fox icon on white background",
    "response_format": "url",
    "size": "1024x1024"
  }'

Text to speech

cURL

curl -X POST "https://cloud.hopegate.ai/api/v1/audio/speech" \
  -H "Authorization: Bearer YOUR_TOKENMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -o speech.mp3 \
  -d '{
    "model": "gpt-4o-mini-tts",
    "provider": "dataeyes",
    "input": "Hello from TokenMarket",
    "voice": "alloy",
    "format": "mp3"
  }'

Rerank

cURL

curl -X POST "https://cloud.hopegate.ai/api/v1/rerank" \
  -H "Authorization: Bearer YOUR_TOKENMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-rerank",
    "provider": "dataeyes",
    "query": "Which document is about TypeScript?",
    "documents": ["TypeScript guide", "Baking bread tutorial", "Marathon training"],
    "top_n": 2
  }'

Video generation

cURL

curl -X POST "https://cloud.hopegate.ai/api/v1/video/generations" \
  -H "Authorization: Bearer YOUR_TOKENMARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v1",
    "provider": "dataeyes",
    "prompt": "A paper plane flying over a lake at sunrise",
    "size": "1280x720"
  }'

Streaming events

Responses SSE event format

When /v1/responses uses stream=true, TokenMarket returns a server-sent event sequence. Consume response.output_text.delta for incremental rendering and response.completed for the final assembled result.

response.created means the response object exists and is usually still in_progress.

response.output_text.delta is the event you should append directly into a live text buffer.

usage.summary reports token and billing totals during the stream, and the sequence ends with data: [DONE].

Example SSE event sequence

event: response.created
data: {"type":"response.created","response":{"id":"resp_123","object":"response","created":1780468890,"model":"gpt-5.4","status":"in_progress"}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"type":"message","id":"msg_resp_123","status":"in_progress","role":"assistant","content":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_resp_123","output_index":0,"content_index":0,"delta":"Hello"}

event: usage.summary
data: {"prompt_tokens":24,"completion_tokens":12,"total_tokens":36,"charged_amount":0.00052}

event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"type":"message","id":"msg_resp_123","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hello","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_123","object":"response","created":1780468890,"status":"completed","output_text":"Hello","output":[{"type":"message","id":"msg_resp_123","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hello","annotations":[]}]}],"model":"gpt-5.4","usage":{"input_tokens":24,"output_tokens":12,"total_tokens":36,"charged_amount":0.00052}}}

data: [DONE]

Different upstream models may chunk text differently, but the event order and outer field semantics stay the same.

Error handling

TokenMarket normalizes platform and upstream failures into a consistent error envelope.

Type	Code	Meaning
invalid_request_body	REQUEST_001	Request body validation failed.
unauthorized	AUTH_001	API key is missing, invalid, or disabled.
provider_error	PROVIDER_001	The upstream service rejected the request or the selected model is unavailable.
timeout	PROVIDER_TIMEOUT	The upstream operation timed out before completion.

FAQ

How do I switch languages?

Use the language switcher in the page header. The route stays on the same document path and changes between English and Chinese.

Do I need different APIs for different model categories?

No. TokenMarket keeps separate unified endpoints by operation type, but they all share the same authentication pattern and base URL.

Why can a model return PROVIDER_001?

That means the request reached the upstream service but failed there, for example because the model is not enabled, the upstream returned an error, or the transport was interrupted.

When should I use /v1/responses?

Use /v1/responses when you want OpenAI Responses-style input or direct SSE event streaming. If you already rely on a chat/completions SDK, you can continue using /v1/chat/completions.

When should I start with /v1/chat/completions?

If you want the smallest integration surface, start with /v1/chat/completions; switch to /v1/responses when you need native Responses-style input or event streaming.