# SeedMaker API for agents

Read the [OpenAPI schema](https://seedmaker.tianlangedu.com.cn/api/v1/openapi.json) for request shapes. This guide, the schema and the [skill index](https://seedmaker.tianlangedu.com.cn/skills/.well-known/agent-skills/index.json) are public.

| Task | Interface | Credentials |
| --- | --- | --- |
| Chat, vision, JSON output, client-side function calling | https://seedmaker.tianlangedu.com.cn/api/openai/v1 | SeedMaker API key, generation scope |
| Media generation, task status, assets and balance | https://seedmaker.tianlangedu.com.cn/api/v1 | SeedMaker API key with the operation’s scope |
| Canvas collaboration and media workflows from an assistant | https://seedmaker.tianlangedu.com.cn/api/mcp | OAuth using Streamable HTTP |

## Chat requests

Send `Authorization: Bearer $SEEDMAKER_API_KEY`. Get the public model IDs from `GET https://seedmaker.tianlangedu.com.cn/api/openai/v1/models`. Use one of those IDs in `POST https://seedmaker.tianlangedu.com.cn/api/openai/v1/chat/completions`. The key determines the workspace, team and budget. Keep it on the client or backend authorized to use it.

| Public model ID | Accepted user input |
| --- | --- |
| `doubao-seed-2-1-pro-260915` | Text and image_url |
| `doubao-seed-2-1-lite-260915` | Text and image_url |
| `doubao-seed-2-1-turbo-260628` | Text and image_url |
| `deepseek-v4-pro-ga-260813` | Text |
| `deepseek-v4-1-flash-261017` | Text and image_url |

```python
import os
from openai import OpenAI

client = OpenAI(base_url="https://seedmaker.tianlangedu.com.cn/api/openai/v1",
                api_key=os.environ["SEEDMAKER_API_KEY"], max_retries=0)
reply = client.chat.completions.create(
    model="deepseek-v4-1-flash-261017",
    messages=[{"role": "user", "content": "Reply with one word for the color of grass."}],
    max_completion_tokens=256,
)
print(reply.choices[0].message.content)
```

Production-tested examples for choosing a model:

| Need | Verified public model IDs |
| --- | --- |
| Plain text | doubao-seed-2-1-pro-260915, doubao-seed-2-1-lite-260915, doubao-seed-2-1-turbo-260628, deepseek-v4-pro-ga-260813, deepseek-v4-1-flash-261017 |
| Two-turn function calling with the original assistant message | doubao-seed-2-1-lite-260915, deepseek-v4-1-flash-261017 |
| JSON object output | doubao-seed-2-1-lite-260915 |
| Visual interpretation of an image_url | deepseek-v4-1-flash-261017 |

Other model/feature combinations have not been verified in this acceptance run. JSON object output ensures a JSON object; validate its fields in your client when a particular schema is required.

Requests are stateless. Send the messages needed for the next turn. For a function call, keep the original assistant message (including tool_calls and any provider reasoning or encrypted fields), run the authorized function in the calling application, and append a tool message with the matching tool_call_id. Use response_format={"type":"json_object"} on models that support JSON output. The OpenAPI request schema describes accepted parameters; providers can further restrict a parameter or modality.

## Streams and billing

Set stream=true for SSE. Accumulate choices[].delta.content for text and assemble tool-call argument deltas by their index before parsing. With stream_options.include_usage=true, normal choice chunks carry usage:null and the final usage chunk has choices:[] before [DONE]. Read the stream through the end to receive totals. On supported reasoning models use max_completion_tokens to bound thinking and answer tokens together; max_tokens can have a different meaning upstream.

Record the response’s x-request-id for SeedMaker billing support. The response body's id identifies the provider completion. A known usage is settled once against the key's workspace. If the client disconnects before receiving usage, billing can still settle when the server received it. If SeedMaker also lacks usage, the request remains pending reconciliation.

## Failures and retries

- 400 or 404: inspect error.message and the live model list; correct the request or select a capable model.
- 401 or 403: check the credential type, expiration, scope and workspace access.
- 402: check the workspace balance and API key budget.
- 429: honor Retry-After when present. Concurrency across keys can share a workspace limit.
- Timeout, truncated stream or 5xx after sending a completion: preserve the request ID when available. A new POST can perform new inference and incur a second charge. Start another generation only when that is the intended action.

## Media and canvases

For media REST, discover the permitted generation models at `GET https://seedmaker.tianlangedu.com.cn/api/v1/models`. Create a task using the operation for the selected media type, keep its ID and poll the matching status route. For MCP, connect through OAuth, call list_models, submit create_generation_task, then poll get_task_status. The [MCP skill](https://seedmaker.tianlangedu.com.cn/skills/.well-known/agent-skills/seedmaker-mcp/SKILL.md) documents workspace placement, asset uploads and live canvas operations.
