BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Recuperar lote
OpenAPI
openapi: 3.1.0
info:
title: QwenCloud Batch API
description: Submit batch inference jobs via file upload at 50% of real-time API cost. OpenAI-compatible.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com/compatible-mode/v1
description: Singapore
security:
- BearerAuth: []
paths:
/batches/{batch_id}:
get:
operationId: retrieveBatch
summary: Retrieve batch
description: Check the status of a batch job and retrieve output file IDs when the job completes.
parameters:
- name: batch_id
in: path
required: true
description: The ID of the batch job to retrieve.
schema:
type: string
example: batch_abc123
responses:
"200":
description: Batch job details
content:
application/json:
schema:
$ref: "#/components/schemas/BatchObject"
"400":
description: Invalid request — invalid batch ID format
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
x-codeSamples:
- lang: python
label: Python
source: |-
from openai import OpenAI
import os
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://maas.qwencloudapi.com/compatible-mode/v1",
)
batch = client.batches.retrieve(batch_id="batch_abc123")
print(f"Status: {batch.status}")
print(f"Output file: {batch.output_file_id}")
print(f"Error file: {batch.error_file_id}")
- lang: javascript
label: Node.js
source: |-
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1",
});
const batch = await client.batches.retrieve("batch_abc123");
console.log(`Status: ${batch.status}`);
console.log(`Output file: ${batch.output_file_id}`);
console.log(`Error file: ${batch.error_file_id}`);
- lang: curl
label: cURL
source: |-
curl -X GET "https://maas.qwencloudapi.com/compatible-mode/v1/batches/batch_abc123" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: QwenCloud API Key. Create one in the [console](https://home.qwencloud.com/api-keys).
schemas:
UploadFileRequest:
type: object
required:
- file
- purpose
properties:
file:
type: string
format: binary
description: The JSONL file to upload. Must be UTF-8 encoded with one JSON object per line. Maximum file size is 500 MB with up to 50,000 requests.
purpose:
type: string
enum:
- batch
description: The intended purpose of the file. Must be `"batch"` for batch processing.
FileObject:
type: object
properties:
id:
type: string
description: Unique file identifier.
example: file-abc123
object:
type: string
enum:
- file
description: Always `"file"`.
bytes:
type: integer
description: File size in bytes.
example: 2048
created_at:
type: integer
description: Unix timestamp (seconds) when the file was uploaded.
example: 1735113344
filename:
type: string
description: Original file name.
example: input.jsonl
purpose:
type: string
enum:
- batch
description: Purpose of the file. Always `"batch"` for batch input files.
status:
type: string
description: Current file status.
example: processed
status_details:
type: string
nullable: true
description: Additional status details. `null` when no details available.
CreateBatchRequest:
type: object
required:
- input_file_id
- endpoint
- completion_window
properties:
input_file_id:
type: string
description: The ID of the uploaded input file. Obtain this from the file upload response.
example: file-abc123
endpoint:
type: string
enum:
- /v1/chat/completions
- /v1/embeddings
- /v1/chat/ds-test
description: The API endpoint for batch requests. Must match the `url` field in the input file. Use `/v1/chat/completions` for text generation, `/v1/embeddings` for embeddings, or `/v1/chat/ds-test` for the test model.
example: /v1/chat/completions
completion_window:
type: string
description: "Maximum time allowed for the batch to complete. Range: `24h` to `336h` (14 days). Supports hour (`h`) and day (`d`) units, e.g., `24h`, `7d`. Integers only."
example: 24h
metadata:
type: object
nullable: true
description: Optional key-value metadata for the batch job.
additionalProperties:
type: string
properties:
ds_name:
type: string
description: Task name. Max 100 characters. If defined multiple times, the last value is used.
example: nightly evaluation
ds_description:
type: string
description: Task description. Max 200 characters. If defined multiple times, the last value is used.
example: Daily model evaluation batch
ds_batch_finish_callback:
type: string
description: Publicly accessible callback URL. The system sends a POST request with task status on completion.
example: https://example.com/callback
example:
ds_name: Task name
ds_description: Task description
BatchObject:
type: object
properties:
id:
type: string
description: Unique batch job identifier.
example: batch_abc123
object:
type: string
enum:
- batch
description: Always `"batch"`.
endpoint:
type: string
description: The API endpoint used for this batch.
example: /v1/chat/completions
errors:
type: object
nullable: true
description: Errors encountered during batch processing.
properties:
object:
type: string
enum:
- list
description: Always `"list"`.
data:
type: array
description: List of error details.
items:
$ref: "#/components/schemas/BatchError"
input_file_id:
type: string
description: ID of the input file.
example: file-abc123
completion_window:
type: string
description: The completion window for the batch job.
example: 24h
status:
type: string
enum:
- validating
- in_progress
- finalizing
- completed
- failed
- expired
- cancelling
- cancelled
description: "Current status of the batch job. `validating`: input file is being validated. `in_progress`: batch is being processed. `finalizing`: results are being compiled. `completed`: all requests finished. `failed`: job failed. `expired`: job exceeded the completion window. `cancelling`: cancellation in progress. `cancelled`: job was cancelled."
output_file_id:
type: string
nullable: true
description: ID of the file containing successful results. Available when status is `completed`. Use with the download file content endpoint.
example: file-xyz789
error_file_id:
type: string
nullable: true
description: ID of the file containing error details. Available when some requests failed. Use with the download file content endpoint.
example: file-err456
created_at:
type: integer
description: Unix timestamp (seconds) when the batch was created.
example: 1735113344
in_progress_at:
type: integer
nullable: true
description: Unix timestamp (seconds) when the batch started processing.
expires_at:
type: integer
nullable: true
description: Unix timestamp (seconds) when the batch will expire.
finalizing_at:
type: integer
nullable: true
description: Unix timestamp (seconds) when the batch started finalizing.
completed_at:
type: integer
nullable: true
description: Unix timestamp (seconds) when the batch completed.
failed_at:
type: integer
nullable: true
description: Unix timestamp (seconds) when the batch failed.
expired_at:
type: integer
nullable: true
description: Unix timestamp (seconds) when the batch expired.
cancelled_at:
type: integer
nullable: true
description: Unix timestamp (seconds) when the batch was cancelled.
cancelling_at:
type: integer
nullable: true
description: Unix timestamp (seconds) when the batch entered cancelling status.
request_counts:
type: object
description: Request processing counts.
properties:
total:
type: integer
description: Total number of requests in the batch.
completed:
type: integer
description: Number of requests that completed successfully.
failed:
type: integer
description: Number of requests that failed.
metadata:
type: object
nullable: true
description: Key-value metadata attached to the batch.
additionalProperties:
type: string
properties:
ds_name:
type: string
description: Task name.
ds_description:
type: string
description: Task description.
BatchError:
type: object
properties:
code:
type: string
description: Error code.
message:
type: string
description: Human-readable error message.
param:
type: string
nullable: true
description: Parameter that caused the error.
line:
type: integer
nullable: true
description: Line number in the input file that caused the error.
BatchResultLine:
type: object
description: A single line from the output JSONL file representing one batch request result.
properties:
id:
type: string
description: Unique result identifier.
custom_id:
type: string
description: The custom_id from the corresponding input request, used for result matching.
example: "1"
response:
type: object
nullable: true
description: Response data for the request.
properties:
status_code:
type: integer
description: HTTP status code of the response.
example: 200
request_id:
type: string
description: Server-generated unique ID for this request.
example: c308ef7f-0824-9c46-96eb-73566f062426
body:
type: object
description: Response body matching the corresponding API response format (e.g., chat completion or embedding response).
properties:
id:
type: string
description: Unique completion identifier.
created:
type: integer
description: Unix timestamp (seconds) when the completion was created.
object:
type: string
description: Object type (e.g., `chat.completion`).
model:
type: string
description: Model used for the completion.
choices:
type: array
description: List of generated replies.
items:
type: object
properties:
index:
type: integer
description: Index of this choice.
message:
type: object
properties:
role:
type: string
description: Always `assistant`.
content:
type: string
description: Generated text.
finish_reason:
type: string
description: Why generation stopped.
usage:
type: object
description: Token usage.
properties:
prompt_tokens:
type: integer
completion_tokens:
type: integer
total_tokens:
type: integer
error:
type: object
nullable: true
description: Error information if the request failed. `null` on success.
properties:
code:
type: string
description: Error code.
message:
type: string
description: Error message.
ErrorResponse:
type: object
properties:
error:
type: object
properties:
message:
type: string
description: Error message.
type:
type: string
description: Error type.
code:
type: string
description: Error code.
param:
type: string
nullable: true
description: Parameter that caused the error.
ListBatchesResponse:
type: object
properties:
object:
type: string
enum:
- list
description: Always `list`.
data:
type: array
description: List of batch objects.
items:
$ref: "#/components/schemas/BatchObject"
first_id:
type: string
nullable: true
description: ID of the first batch in the list.
example: batch_abc123
last_id:
type: string
nullable: true
description: ID of the last batch in the list.
example: batch_abc456
has_more:
type: boolean
description: Whether there are more batches available after this page.