Calling Guide

Pre-Call Confirmation

Administrators need to first install plugins, configure channels, and set prices. Callers use their own New API 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 New API, 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 New API 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.

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.