ARAYA Public API
- OpenAPI Version:
3.1.0 - API Version:
2026-05-19
Public REST API for ARAYA video projects, renders, credits, API keys, and webhooks.
Each API key carries a set of scopes. Available scopes: projects:read, projects:write, renders:create, billing:read, webhooks:write, api_keys:write. Managing API keys (POST /v1/api-keys, rotate, delete) requires the api_keys:write scope. A key minted through the API cannot grant scopes the issuing key does not itself hold.
Contents
Operations
- GET /v1/projects
- POST /v1/projects
- GET /v1/projects/{project_uuid}
- DELETE /v1/projects/{project_uuid}
- POST /v1/projects/{project_uuid}/upload-url
- POST /v1/projects/{project_uuid}/upload-completed
- GET /v1/projects/{project_uuid}/scenes
- PUT /v1/projects/{project_uuid}/scenes
- GET /v1/projects/{project_uuid}/render-settings
- PUT /v1/projects/{project_uuid}/render-settings
- GET /v1/projects/{project_uuid}/render-estimate
- GET /v1/projects/{project_uuid}/renders
- POST /v1/projects/{project_uuid}/renders
- GET /v1/jobs/{job_uuid}
- GET /v1/jobs/{job_uuid}/artifacts
- POST /v1/jobs/{job_uuid}/cancel
- GET /v1/credits/balance
- GET /v1/webhooks
- POST /v1/webhooks
- POST /v1/webhooks/{webhook_uuid}/rotate
- DELETE /v1/webhooks/{webhook_uuid}
- POST /v1/api-keys
- POST /v1/api-keys/{api_key_uuid}/rotate
Schemas
- Meta
- ErrorEnvelope
- Project
- ProjectEnvelope
- ProjectListEnvelope
- CreateProjectRequest
- DeleteEnvelope
- CreateUploadRequest
- UploadSessionEnvelope
- JobQueuedEnvelope
- SceneInput
- SceneListEnvelope
- RenderSettingsInput
- RenderSettingsEnvelope
- CreateWebhookRequest
Servers
- URL:
https://stg.video.araya.org
Authentication
- ApiKeyHeader: API key in header
X-API-Key
Or:
- ApiKeyBearer: HTTP bearer
Tags
Projects
Uploads
Scenes
Render Settings
Renders
Jobs
Credits
Webhooks
Deliveries sign the raw HTTP body with HMAC-SHA256 over <timestamp>.<body>. X-Araya-Signature is t=<unix>,v1=<hex> normally, and t=<unix>,v1=<new-key hex>,v1=<previous-key hex> during the 24-hour rotation grace period. Preserve every repeated v1 value; do not parse the header into a single-value map. Require the signed timestamp to match X-Araya-Timestamp and fall within a five-minute window. Compute the expected HMAC with your configured key and compare all v1 candidates in constant time, accepting the delivery when any candidate matches. Creation and rotation return signing_secret once; replay omits it. If the response or key is lost, disable the endpoint with DELETE /v1/webhooks/{webhook_uuid}, create a replacement with POST /v1/webhooks, and configure its new key at your receiver. Delivery stops for the disabled endpoint. Replaying the request cannot recover the key, and another rotation is unavailable during the grace period.
API Keys
Operations
GET /v1/projects
- Method:
GET - Path:
/v1/projects - Operation ID:
listProjects - Tags: Projects
Servers: Inherited servers
Authentication
- ApiKeyHeader: API key in header
X-API-Key
Query parameters
cursor:stringlimit:integer, default:50, minimum:1, maximum:100
Responses
200 Projects.
Content type: application/json
Generated example:
{
"data": [
{
"uuid": "",
"name": "",
"status": "",
"source_filename": null,
"duration_seconds": null,
"width": null,
"height": null,
"language": "",
"uploaded_at": null,
"analyzed_at": null,
"completed_at": null,
"created_at": null
}
],
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}POST /v1/projects
- Method:
POST - Path:
/v1/projects - Operation ID:
createProject - Tags: Projects
Servers: Inherited servers
Authentication: Global authentication
Header parameters
Idempotency-Key(required):string, maxLength:255
Request body
Required: true
Content type: application/json
Generated example:
{
"name": "",
"source_filename": null,
"duration_seconds": null,
"width": null,
"height": null,
"language": "ja"
}Responses
201 Created project.
Content type: application/json
Generated example:
{
"data": {
"uuid": "",
"name": "",
"status": "",
"source_filename": null,
"duration_seconds": null,
"width": null,
"height": null,
"language": "",
"uploaded_at": null,
"analyzed_at": null,
"completed_at": null,
"created_at": null
},
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}GET /v1/projects/{project_uuid}
- Method:
GET - Path:
/v1/projects/{project_uuid} - Operation ID:
getProject - Tags: Projects
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Responses
200 Project.
Content type: application/json
DELETE /v1/projects/{project_uuid}
- Method:
DELETE - Path:
/v1/projects/{project_uuid} - Operation ID:
deleteProject - Tags: Projects
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Header parameters
Idempotency-Key(required):string, maxLength:255
Responses
200 Project deleted.
Content type: application/json
Generated example:
{
"data": {
"deleted": true
},
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}POST /v1/projects/{project_uuid}/upload-url
- Method:
POST - Path:
/v1/projects/{project_uuid}/upload-url - Operation ID:
createUploadUrl - Tags: Uploads
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Header parameters
Idempotency-Key(required):string, maxLength:255
Request body
Required: true
Content type: application/json
Generated example:
{
"filename": "",
"mime_type": "",
"size_bytes": 1
}Responses
201 Resumable upload session.
Content type: application/json
Generated example:
{
"data": {
"upload_session_uuid": "",
"session_uri": "",
"chunk_size": 1,
"expires_at": null
},
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}POST /v1/projects/{project_uuid}/upload-completed
- Method:
POST - Path:
/v1/projects/{project_uuid}/upload-completed - Operation ID:
completeUpload - Tags: Uploads
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Header parameters
Idempotency-Key(required):string, maxLength:255
Request body
Required: true
Content type: application/json
upload_session_uuid(required):string
Generated example:
{
"upload_session_uuid": ""
}Responses
202 Analyze job queued.
Content type: application/json
Generated example:
{
"data": {
"job_uuid": "",
"project_uuid": "",
"status": "",
"estimated_credits": 1,
"reserved_credits": 1
},
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}GET /v1/projects/{project_uuid}/scenes
- Method:
GET - Path:
/v1/projects/{project_uuid}/scenes - Operation ID:
listScenes - Tags: Scenes
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Responses
200 Scenes.
Content type: application/json
Generated example:
{
"data": [
{
"scene_index": 1,
"start_ms": 1,
"end_ms": 1,
"subtitle_text": "",
"narration_text": null,
"narration_uses_subtitle": true,
"is_locked": true
}
],
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}PUT /v1/projects/{project_uuid}/scenes
- Method:
PUT - Path:
/v1/projects/{project_uuid}/scenes - Operation ID:
updateScenes - Tags: Scenes
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Header parameters
Idempotency-Key(required):string, maxLength:255
Request body
Required: true
Content type: application/json
scenes(required): array of SceneInput
Generated example:
{
"scenes": [
{
"scene_index": 1,
"start_ms": 1,
"end_ms": 1,
"subtitle_text": "",
"narration_text": null,
"narration_uses_subtitle": true,
"is_locked": true
}
]
}Responses
200 Updated scenes.
Content type: application/json
GET /v1/projects/{project_uuid}/render-settings
- Method:
GET - Path:
/v1/projects/{project_uuid}/render-settings - Operation ID:
getRenderSettings - Tags: Render Settings
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Responses
200 Render settings.
Content type: application/json
Generated example:
{
"data": {
"voice_id": "",
"tts_volume": 1,
"bgm_key": null,
"bgm_volume": 1,
"subtitle_style": {
"font_size": 1,
"position": "top",
"position_percent": 0,
"color": "",
"background_color": "",
"background_opacity": 0,
"stroke_color": "",
"stroke_width": 0
},
"end_card_settings": {
"cards": [
{
"asset_id": 1,
"duration_sec": 0.5,
"offset_x": -2000,
"offset_y": -2000,
"scale": 0.1,
"background_color": "#000000"
}
]
},
"pronunciation_dictionary": [
{
"surface": "",
"reading": ""
}
],
"output_width": 1,
"output_height": 1,
"fps": 24
},
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}PUT /v1/projects/{project_uuid}/render-settings
- Method:
PUT - Path:
/v1/projects/{project_uuid}/render-settings - Operation ID:
updateRenderSettings - Tags: Render Settings
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Header parameters
Idempotency-Key(required):string, maxLength:255
Request body
Required: true
Content type: application/json
Generated example:
{
"voice_id": "",
"tts_volume": 1,
"bgm_key": null,
"bgm_volume": 1,
"subtitle_style": {
"font_size": 1,
"position": "top",
"position_percent": 0,
"color": "",
"background_color": "",
"background_opacity": 0,
"stroke_color": "",
"stroke_width": 0
},
"end_card_settings": {
"cards": [
{
"asset_id": 1,
"duration_sec": 0.5,
"offset_x": -2000,
"offset_y": -2000,
"scale": 0.1,
"background_color": "#000000"
}
]
},
"pronunciation_dictionary": [
{
"surface": "",
"reading": ""
}
],
"output_width": 1,
"output_height": 1,
"fps": 24
}Responses
200 Updated render settings.
GET /v1/projects/{project_uuid}/render-estimate
- Method:
GET - Path:
/v1/projects/{project_uuid}/render-estimate - Operation ID:
estimateRender - Tags: Render Settings
Returns the credit estimate for the project's saved render settings.
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Responses
200 Credit estimate.
404 Render settings have not been saved for this project yet.
GET /v1/projects/{project_uuid}/renders
- Method:
GET - Path:
/v1/projects/{project_uuid}/renders - Operation ID:
listRenders - Tags: Renders
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Responses
200 Render jobs.
POST /v1/projects/{project_uuid}/renders
- Method:
POST - Path:
/v1/projects/{project_uuid}/renders - Operation ID:
createRender - Tags: Renders
Servers: Inherited servers
Authentication: Global authentication
Path parameters
project_uuid(required):string
Header parameters
Idempotency-Key(required):string, maxLength:255
Responses
202 Render queued.
Content type: application/json
GET /v1/jobs/{job_uuid}
- Method:
GET - Path:
/v1/jobs/{job_uuid} - Operation ID:
getJob - Tags: Jobs
Returns a render, rerender or analyze job. The analyze job UUID comes from upload-completed; artifacts and cancel accept render jobs only.
Servers: Inherited servers
Authentication: Global authentication
Path parameters
job_uuid(required):string
Responses
200 Job.
GET /v1/jobs/{job_uuid}/artifacts
- Method:
GET - Path:
/v1/jobs/{job_uuid}/artifacts - Operation ID:
listJobArtifacts - Tags: Jobs
Servers: Inherited servers
Authentication: Global authentication
Path parameters
job_uuid(required):string
Responses
200 Render artifacts.
POST /v1/jobs/{job_uuid}/cancel
- Method:
POST - Path:
/v1/jobs/{job_uuid}/cancel - Operation ID:
cancelJob - Tags: Jobs
Servers: Inherited servers
Authentication: Global authentication
Path parameters
job_uuid(required):string
Header parameters
Idempotency-Key(required):string, maxLength:255
Responses
200 Canceled job.
GET /v1/credits/balance
- Method:
GET - Path:
/v1/credits/balance - Operation ID:
getCreditBalance - Tags: Credits
Servers: Inherited servers
Authentication: Global authentication
Responses
200 Credit balance.
GET /v1/webhooks
- Method:
GET - Path:
/v1/webhooks - Operation ID:
listWebhooks - Tags: Webhooks
Servers: Inherited servers
Authentication: Global authentication
Responses
200 Webhooks.
POST /v1/webhooks
- Method:
POST - Path:
/v1/webhooks - Operation ID:
createWebhook - Tags: Webhooks
Servers: Inherited servers
Authentication: Global authentication
Header parameters
Idempotency-Key(required):string, maxLength:255
Request body
Required: true
Content type: application/json
Generated example:
{
"url": "https://example.com",
"description": null,
"events": [
"render.completed"
]
}Responses
201 Registered webhook. signing_secret is returned only once; idempotent replay omits it.
POST /v1/webhooks/{webhook_uuid}/rotate
- Method:
POST - Path:
/v1/webhooks/{webhook_uuid}/rotate - Operation ID:
rotateWebhookSecret - Tags: Webhooks
Returns signing_secret once. Previous key remains valid for 24 hours; rotations during that grace period are rejected. Idempotent replay omits the secret.
Servers: Inherited servers
Authentication: Global authentication
Path parameters
webhook_uuid(required):string
Header parameters
Idempotency-Key(required):string, maxLength:255
Responses
200 New signing secret (one-time response).
404 Endpoint does not belong to the authenticated user.
422 Endpoint is disabled or still in a rotation grace period (webhook_rotation_unavailable).
Content type: application/json
Generated example:
{
"error": {
"code": "",
"message": "",
"details": {},
"request_id": ""
}
}DELETE /v1/webhooks/{webhook_uuid}
- Method:
DELETE - Path:
/v1/webhooks/{webhook_uuid} - Operation ID:
deleteWebhook - Tags: Webhooks
Servers: Inherited servers
Authentication: Global authentication
Path parameters
webhook_uuid(required):string
Responses
200 Disabled webhook.
POST /v1/api-keys
- Method:
POST - Path:
/v1/api-keys - Operation ID:
createApiKey - Tags: API Keys
Requires the api_keys:write scope. The scopes of the new key must be a subset of the issuing key's scopes; otherwise the request is rejected with 400 (invalid_request). data.plain_text is returned once and never stored in idempotency history. Replaying the same Idempotency-Key omits it. If lost, revoke the key and issue a replacement.
Servers: Inherited servers
Authentication: Global authentication
Header parameters
Idempotency-Key(required):string, maxLength:255
Responses
201 Created API key.
POST /v1/api-keys/{api_key_uuid}/rotate
- Method:
POST - Path:
/v1/api-keys/{api_key_uuid}/rotate - Operation ID:
rotateApiKey - Tags: API Keys
Requires api_keys:write. Returns data.plain_text only on the initial response; idempotent replay omits it and never recovers a lost key. Revoke the new key and issue a replacement if lost. The previous key retains its 24-hour grace period.
Servers: Inherited servers
Authentication: Global authentication
Path parameters
api_key_uuid(required):string
Header parameters
Idempotency-Key(required):string, maxLength:255
Responses
201 Rotated API key; plain_text is returned once.
Schemas
Meta
Type: object
api_version(required):stringrequest_id(required):stringhas_more:booleannext_cursor:string | null
Generated example:
{
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}ErrorEnvelope
Type: object
error(required):objectcode(required):stringmessage(required):stringrequest_id(required):stringdetails:object
Generated example:
{
"error": {
"code": "",
"message": "",
"details": {},
"request_id": ""
}
}Project
Type: object
language(required):stringname(required):stringstatus(required):stringuuid(required):stringanalyzed_at:string | null, format:date-timecompleted_at:string | null, format:date-timecreated_at:string | null, format:date-timeduration_seconds:integer | nullheight:integer | nullsource_filename:string | nulluploaded_at:string | null, format:date-timewidth:integer | null
Generated example:
{
"uuid": "",
"name": "",
"status": "",
"source_filename": null,
"duration_seconds": null,
"width": null,
"height": null,
"language": "",
"uploaded_at": null,
"analyzed_at": null,
"completed_at": null,
"created_at": null
}ProjectEnvelope
Type: object
Generated example:
{
"data": {
"uuid": "",
"name": "",
"status": "",
"source_filename": null,
"duration_seconds": null,
"width": null,
"height": null,
"language": "",
"uploaded_at": null,
"analyzed_at": null,
"completed_at": null,
"created_at": null
},
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}ProjectListEnvelope
Type: object
Generated example:
{
"data": [
{
"uuid": "",
"name": "",
"status": "",
"source_filename": null,
"duration_seconds": null,
"width": null,
"height": null,
"language": "",
"uploaded_at": null,
"analyzed_at": null,
"completed_at": null,
"created_at": null
}
],
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}CreateProjectRequest
Type: object
language(required):string, possible values:"ja", "en"name(required):string, maxLength:255duration_seconds:integer | nullheight:integer | nullsource_filename:string | null, maxLength:255width:integer | null
Generated example:
{
"name": "",
"source_filename": null,
"duration_seconds": null,
"width": null,
"height": null,
"language": "ja"
}DeleteEnvelope
Type: object
data:objectdeleted:boolean
meta: Meta
Generated example:
{
"data": {
"deleted": true
},
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}CreateUploadRequest
Type: object
filename(required):stringmime_type(required):stringsize_bytes(required):integer
Generated example:
{
"filename": "",
"mime_type": "",
"size_bytes": 1
}UploadSessionEnvelope
Type: object
data:objectchunk_size:integerexpires_at:string | null, format:date-timesession_uri:stringupload_session_uuid:string
meta: Meta
Generated example:
{
"data": {
"upload_session_uuid": "",
"session_uri": "",
"chunk_size": 1,
"expires_at": null
},
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}JobQueuedEnvelope
Type: object
data:objectestimated_credits:integerjob_uuid:stringproject_uuid:stringreserved_credits:integerstatus:string
meta: Meta
Generated example:
{
"data": {
"job_uuid": "",
"project_uuid": "",
"status": "",
"estimated_credits": 1,
"reserved_credits": 1
},
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}SceneInput
Type: object
end_ms(required):integerscene_index(required):integerstart_ms(required):integersubtitle_text(required):stringis_locked:booleannarration_text:string | nullnarration_uses_subtitle:boolean
Generated example:
{
"scene_index": 1,
"start_ms": 1,
"end_ms": 1,
"subtitle_text": "",
"narration_text": null,
"narration_uses_subtitle": true,
"is_locked": true
}SceneListEnvelope
Type: object
data: array of SceneInputmeta: Meta
Generated example:
{
"data": [
{
"scene_index": 1,
"start_ms": 1,
"end_ms": 1,
"subtitle_text": "",
"narration_text": null,
"narration_uses_subtitle": true,
"is_locked": true
}
],
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}RenderSettingsInput
Type: object
bgm_volume(required):integerfps(required):integer, possible values:24, 30, 60output_height(required):integeroutput_width(required):integersubtitle_style(required):objectcolor(required):stringfont_size(required):integerposition(required):string, possible values:"top", "middle", "bottom", "custom"background_color:stringbackground_opacity:number, minimum:0, maximum:1position_percent:integer, minimum:0, maximum:100stroke_color:stringstroke_width:integer, minimum:0, maximum:24
tts_volume(required):integervoice_id(required):stringbgm_key:string | nullend_card_settings:object | null, no additional propertiescards(required):array, maxItems:5Items:
no additional properties
asset_id(required):integerduration_sec(required):number, minimum:0.5, maximum:30offset_x(required):number, minimum:-2000, maximum:2000offset_y(required):number, minimum:-2000, maximum:2000scale(required):number, minimum:0.1, maximum:3background_color:string, default:"#000000", pattern:^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$Card background color, drawn in the letterbox bands when the image is fitted inside the frame and behind transparent areas. Defaults to black.
pronunciation_dictionary:arrayItems:
reading:stringsurface:string
Generated example:
{
"voice_id": "",
"tts_volume": 1,
"bgm_key": null,
"bgm_volume": 1,
"subtitle_style": {
"font_size": 1,
"position": "top",
"position_percent": 0,
"color": "",
"background_color": "",
"background_opacity": 0,
"stroke_color": "",
"stroke_width": 0
},
"end_card_settings": {
"cards": [
{
"asset_id": 1,
"duration_sec": 0.5,
"offset_x": -2000,
"offset_y": -2000,
"scale": 0.1,
"background_color": "#000000"
}
]
},
"pronunciation_dictionary": [
{
"surface": "",
"reading": ""
}
],
"output_width": 1,
"output_height": 1,
"fps": 24
}RenderSettingsEnvelope
Type: object
data: RenderSettingsInputmeta: Meta
Generated example:
{
"data": {
"voice_id": "",
"tts_volume": 1,
"bgm_key": null,
"bgm_volume": 1,
"subtitle_style": {
"font_size": 1,
"position": "top",
"position_percent": 0,
"color": "",
"background_color": "",
"background_opacity": 0,
"stroke_color": "",
"stroke_width": 0
},
"end_card_settings": {
"cards": [
{
"asset_id": 1,
"duration_sec": 0.5,
"offset_x": -2000,
"offset_y": -2000,
"scale": 0.1,
"background_color": "#000000"
}
]
},
"pronunciation_dictionary": [
{
"surface": "",
"reading": ""
}
],
"output_width": 1,
"output_height": 1,
"fps": 24
},
"meta": {
"request_id": "",
"api_version": "",
"next_cursor": null,
"has_more": true
}
}CreateWebhookRequest
Type: object
events(required):arrayItems:
string, possible values:"render.completed", "render.failed"url(required):string, format:uridescription:string | null
Generated example:
{
"url": "https://example.com",
"description": null,
"events": [
"render.completed"
]
}