Calling Guide

Pre-Call Confirmation

Administrators need to first install plugins, configure channels, and set prices. Callers use their own ModelRouter instance's API key and confirm that the key can access the corresponding models and groups.

https://your-newapi.example on this page is an instance address placeholder, not the official website. The official website is for browsing and downloading plugins; actual requests are sent to your configured instance.

Check the plugin's supported endpoints and models in the Plugin Marketplace details. Not every plugin supports all protocols listed below.

General Task API

Submit Task

curl 'https://your-newapi.example/v1/tasks/<plugin-key>' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<model>",
    "prompt": "一只小猫在窗边看雨"
  }'

Replace <plugin-key>, <model>, and <NEW_API_KEY>. model is a required field; other fields are determined by the request construction logic of the selected plugin. The above is a schematic representation of the request structure; specific plugins may require images, videos, duration, or other fields; not all plugins accept requests with only prompt.

The general submission response includes the public task ID generated by ModelRouter, for example:

{
  "id": "<public-task-id>",
  "task_id": "<public-task-id>",
  "status": "queued",
  "model": "<model>",
  "created_at": 1780000000
}

Save the returned task_id. Subsequent queries use this public ID, not the internal task ID returned by the upstream vendor.

Query Status

curl 'https://your-newapi.example/v1/tasks/<public-task-id>' \
  -H 'Authorization: Bearer <NEW_API_KEY>'

The query response directly includes task_id, platform, status, progress, fail_reason, created_at, and finished_at. Tasks may go through NOT_START, SUBMITTED, QUEUED, IN_PROGRESS, eventually entering SUCCESS or FAILURE.

Query at reasonable intervals and stop polling after a final state is reached; do not assume that the general query response will return the original upstream payload or artifact URL. See fail_reason for failure reasons, and contact the instance administrator to check task logs if necessary.

Get Artifacts

curl 'https://your-newapi.example/v1/tasks/<public-task-id>/artifacts' \
  -H 'Authorization: Bearer <NEW_API_KEY>'

When the plugin supports artifacts, the artifacts array in the response contains stable key, type, optional mime_type, and content_url. Use the actual returned key; do not assume all plugins use video.

You can read the returned content_url, or download it via the content interface with an API key:

curl 'https://your-newapi.example/v1/tasks/<public-task-id>/artifacts/<artifact-key>/content' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  --output result.bin

Plugin Native Routing

Plugins can provide vendor-style native interfaces via meta.routes. Use the actual path, HTTP method, and request structure listed in the marketplace details, still sending requests to your own ModelRouter instance and providing your instance API key.

The response encapsulation for native routes is determined by the plugin; the general task response fields above cannot be directly applied to all native interfaces. Query routes are first validated for task ownership by the host; submission and dynamic routes will also check model scope based on declarations.

Native paths may include a plugin prefix, such as /doubao/api/v3/... or /ali/api/v1/...; do not use the vendor path as the gateway path without checking it. For an immediate-completion route declaring retainResult: false, save the result from the create response. Later result queries and artifact endpoints are unavailable, while billing and task logs remain.

OpenAI Image compatible interface

Plugins declaring openai_image can handle generation and editing for supported models. Both operations wait for results within the current request. They do not return a task handle for polling through the image protocol or declare the Responses stream / sync / background modes. Generation accepts JSON; editing accepts JSON or multipart, with fields determined by the plugin.

curl 'https://your-newapi.example/v1/images/generations' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<supported-image-model>",
    "prompt": "A kitten by the window",
    "n": 1,
    "response_format": "b64_json"
  }'

curl 'https://your-newapi.example/v1/images/edits' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  --form-string 'model=<supported-image-model>' \
  -F 'prompt=Combine the two reference images into an illustration' \
  -F 'image[]=@reference-1.png' \
  -F 'image[]=@reference-2.png'

Replace the model, key, and local image paths. Use repeated image[] fields only if the plugin and model support editing multiple images. Let curl generate the multipart Content-Type and boundary.

A successful response contains created and data; image entries may include url, b64_json, and optional revised_prompt. For response_format: "b64_json", the host attempts to download images and add Base64. A failed download may leave only the URL, which clients should handle.

For asynchronous upstream tasks, the host polls within the request. Waiting beyond TASK_PLUGIN_PROTOCOL_TIMEOUT_SECONDS (600 seconds by default) returns 504 task_timeout; a failed task returns 400 with its failure reason. Disconnecting or timing out does not cancel a submitted task: background processing and settlement continue. Check task logs before retrying.

Immediate terminal image results are not retained for later retrieval, so save the images from the response. Tasks completed through in-request polling retain the saved snapshot; the Image protocol itself provides no image retrieval endpoint.

OpenAI Video Compatible Interface

Only plugins declaring openai_video will participate in routing for this protocol.

curl 'https://your-newapi.example/v1/videos' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<supported-video-model>",
    "prompt": "海边日出，缓慢向前移动的镜头"
  }'

curl 'https://your-newapi.example/v1/videos/<video-id>' \
  -H 'Authorization: Bearer <NEW_API_KEY>'

The protocol entry supports JSON or multipart; specific fields and formats still depend on the plugin's decoding logic. The artifact content interface is GET /v1/videos/{video-id}/content, also supporting HEAD.

Video queries can retain extended fields provided by the plugin; standard ID, model, status, and time fields are uniformly projected by the host. Queries read saved task snapshots and do not necessarily query upstream in real-time every time.

Responses Compatible Interface

Plugins declaring openai_responses will explicitly announce supported request patterns:

Here's an example with a plugin supporting background:

curl 'https://your-newapi.example/v1/responses' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<supported-responses-model>",
    "input": "生成一幅山间日出的插画",
    "background": true
  }'

curl 'https://your-newapi.example/v1/responses/<response-id>' \
  -H 'Authorization: Bearer <NEW_API_KEY>'

The request content must conform to the plugin's decodeRequest convention. Undeclared patterns will be rejected during the channel selection phase and will not automatically gain streaming or background capabilities just because they belong to the Responses protocol. Querying an already created Response is an independent operation, not a fourth pattern.

Media artifacts in Responses use artifact addresses generated by the host. Even if the upstream uses an SSE submission interface, it does not mean that upstream events will be directly proxied to the client.