Callable model IDs and starting inference
This contract matches deployed revision f09a2d5da1c9b6fbfd95ae4246080a8489d44564 and Go build 7ba12de+oneaster.0.1.0. Use a personal inference API Key (ONEASTER_API_KEY) on /v1 and a native login access_token (ONEASTER_ACCESS_TOKEN) on /pg. Always pass the callable model identifier (model_name in /oneaster/v1/model-catalog, or id in /v1/models) in the model parameter; never pass the admin-editable display_name as model.
curl "$BASE_URL/v1/models" -H "Authorization: Bearer $ONEASTER_API_KEY"
curl "$BASE_URL/v1/chat/completions" -H "Authorization: Bearer $ONEASTER_API_KEY" -H 'Content-Type: application/json' -d '{"model":"YOUR_MODEL_NAME","messages":[{"role":"user","content":"Hello"}],"stream":false}'
Text protocols (/v1 and /pg)
POST /v1/chat/completions, POST /v1/responses, POST /v1/messages and their logged-in counterparts POST /pg/chat/completions, POST /pg/responses, POST /pg/messages speak OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages respectively, supporting JSON, SSE streaming, and tool calls. GET /v1/responses/{response_id} and GET /pg/responses/{response_id} retrieve responses by ID. /v1 routes do not use /pg persistent intents; do not treat Idempotency-Key as a required header on /v1/chat/completions. Legacy Core Responses storage, previous_response_id continuation, and DELETE /v1/responses/{id} are not migrated.
Image generation, edits, and PR #46 extensions
POST /v1/images/generations and POST /pg/images/generations accept JSON; POST /v1/images/edits and POST /pg/images/edits accept either JSON (image or images URL / Data URL) or multipart/form-data file uploads. PR #46 adds optional extension fields to image generation and edit requests: complexity (string), markup (string in JSON or file upload in multipart /images/edits), svg (boolean), frame_count (integer), and frame_duration_ms (integer), alongside aspect_ratio, resolution, seed, negative_prompt, output_format, background, moderation, output_compression, watermark, prompt_upsampling, and safety_tolerance.
Standard video and protected binary downloads
POST /v1/videos and POST /pg/videos create video tasks, GET /v1/videos/{task_id} and GET /pg/videos/{task_id} poll status, and GET or HEAD /v1/videos/{task_id}/content and /pg/videos/{task_id}/content download MP4 bytes. Protected content endpoints require an Authorization: Bearer header; browser video or audio elements cannot fetch them directly without credentials. Fetch the binary stream with Authorization: Bearer, convert the response to a Blob, and pass URL.createObjectURL(blob) to the media element.
Synchronous speech/audio vs. asynchronous KIE Suno music tasks (PR #42)
Standard synchronous speech/transcription routes and asynchronous music generation tasks use distinct contracts. There is no /v1/audio/generations or /pg/audio/generations alias.
First, synchronous audio routes: POST /v1/audio/speech and POST /pg/audio/speech take JSON (model, input, voice, optional response_format mp3/wav/opus/aac/flac/pcm, speed, stream_format audio/sse) and return binary audio bytes or SSE chunks (on /pg/requests/by-intent recovery, binary speech responses up to 4 MiB use response.encoding = "base64"). POST /v1/audio/transcriptions, POST /v1/audio/translations, POST /pg/audio/transcriptions, and POST /pg/audio/translations take multipart/form-data with required model and file (up to 50 MiB).
curl --request POST "https://api.oneaster.ai/pg/audio/transcriptions" \ --header "Authorization: Bearer $ONEASTER_ACCESS_TOKEN" \ --header "Idempotency-Key: $ONEASTER_INTENT" \ --form "model=YOUR_AUDIO_MODEL_NAME" \ --form "[email protected];type=audio/wav"
Second, asynchronous KIE Suno music tasks: call POST /v1/tasks/kie (API Key) or POST /pg/tasks/kie (login access_token). On /pg/tasks/kie, submit model: "ai-music-api/generate", n: 1, prompt (<= 3000 chars), and audio: { mode: "music", music_version: "V6" | "V6_MINI" | "V6_WILD" (default "V6"), custom_mode: boolean, instrumental: boolean, style (<= 1000 chars), lyrics (<= 5000 chars; style or lyrics must be non-empty), title (<= 80 chars, required when custom_mode=true), duration (omit or use 0 for unspecified; nonzero integer 10..360 seconds only when custom_mode=true) }.
curl --request POST "https://api.oneaster.ai/pg/tasks/kie" \
--header "Authorization: Bearer $ONEASTER_ACCESS_TOKEN" \
--header "Idempotency-Key: $ONEASTER_INTENT" \
--header "Content-Type: application/json" \
--data '{"model":"ai-music-api/generate","prompt":"Warm lo-fi piano loop for late night coding","n":1,"audio":{"mode":"music","music_version":"V6","custom_mode":false,"instrumental":true,"style":"Warm lo-fi piano"}}'
A completed Suno music task produces two MP3 tracks (keys audio-0 and audio-1). Poll GET /pg/tasks/{task_id} (or GET /v1/tasks/{id}) every 3–5 seconds until terminal, call GET /pg/tasks/{task_id}/artifacts (or GET /v1/tasks/{id}/artifacts) to inspect artifacts[] (key, type, mime_type, content_url; no title, duration, or cover metadata), and download each track via GET /pg/tasks/{task_id}/artifacts/{artifact_key}/content with Authorization: Bearer to create a Blob URL. Generic task states are NOT_START, SUBMITTED, QUEUED, IN_PROGRESS, SUCCESS, FAILURE, and UNKNOWN; never treat UNKNOWN as refunded or automatically retry it.